How to document an array of strings?

[Jeeppler]

I already looked at #87 and at spring-restdocs#505. I am using restDocsApiSpec: "0.10.0".

My API api/admin/users returns a JSON Array containing only strings: ["user1", "user2", "user3"].

What I currently get is:

api-admin-users1367467944:
  type: array
  items:
    type: object

the corresponding Java Code:

responseFields(
  fieldWithPath("[]").description("List of user Ids").optional()
).

What I want is:

api-admin-users1367467944:
  type: array
  items:
    type: string

Is there already a workaround for documenting an array of strings in ePages-de/restdoc-api-spec? Would somebody be willing to share an example on how to do it?

[al3x3i]

I am not sure if this can help you, you can try fieldWithPath("[]").description("List of user Ids").optional().type(STRING)

[ozscheyge]

I am not sure if this can help you, you can try fieldWithPath("[]").description("List of user Ids").optional().type(STRING)

That's not correct, since the type of the field is not STRING, but ARRAY.

@Jeeppler thanks for reaching out! Idk how this would be done with idiomatic Spring restdocs, since it only allows to document and render the field type (ARRAY in this case).

restdocs-api-spec has some more logic to infer types for the jsonschema: https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-jsonschema/src/main/kotlin/com/epages/restdocs/apispec/jsonschema/JsonSchemaFromFieldDescriptorsGenerator.kt#L228 https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-jsonschema/src/main/kotlin/com/epages/restdocs/apispec/jsonschema/JsonSchemaFromFieldDescriptorsGenerator.kt#L206

Those parts would need to be improved.

[Jeeppler]

@ozscheyge thanks for your response. Based on the links you provided ePages should be able to recognize the array type. However, I was unable to find any documentation on how to do that. Is there a non idiomatic Spring restdocs way using ePages? Would you be willing to share an example or point me to one?

[ozscheyge]

Hey @Jeeppler ,

I was only pointing out, which parts of the codebase are responsible for the current behavior and would need to be improved (inference of the JSON schema from example payloads).

With "idiomatic Spring restdocs" I meant proper usage of Spring restdocs according to their API design and philosophy. This project (restdocs-api-spec) aims to be import-swap-compatible with Spring restdocs, see https://github.com/ePages-de/restdocs-api-spec#migrate-existing-spring-rest-docs-tests . So we are constrained by Spring restdocs capabilities and -for instance- the issue you linked in your original post. That's also the reason you won't find detailed docs on how to document your tests and payloads using this project: it should be the same as with Spring restdocs, using the same classes and factory methods.

Unfortunately, I don't see an idiomatic way of documenting an array of enum values using Spring restdocs. We could make the JSON schema inference a bit smarter, but it might still be insufficient to match OpenAPI 3 capabilities of exactly specifying possible enum values as elements in an array.

edit: What we currently do, when we need to document an array of enum values or enums in general: We list the possible values in the field description using some utility function to generate a formatted string of possible enum values from an enum Java class. This is in accordance with Spring restdocs, but doesn't leverage the capabilities of OpenAPI 3 and JSON schema to exactly specify the allowed values. :|

With asciidoctor it renders like this:

The relevant part of the resource.json file:

    }, {
      "attributes" : {
        "validationConstraints" : [ ],
        "constraints" : ""
      },
      "description" : "The areas in which the app can be used and advertised. Can be one or more of `SHIPPING`, `LEGAL`, `MARKETING`, `STOREFRONT`, `PRODUCT_IMAGE`, `PAYMENT`, `ORDER`, or `EMBEDDED_IN_NAVIGATION`. See <<resource-app-categories-get>> for details.",
      "ignored" : false,
      "path" : "categories",
      "type" : "ARRAY",
      "optional" : false
    }, {

The currently generated schema in OpenAPI 3:

        categories:
          type: array
          description: The areas in which the app can be used and advertised. Can
            be one or more of `SHIPPING`, `LEGAL`, `MARKETING`, `STOREFRONT`, `PRODUCT_IMAGE`,
            `PAYMENT`, `ORDER`, or `EMBEDDED_IN_NAVIGATION`. See <<resource-app-categories-get>>
            for details.
          items:
            oneOf:
            - type: object
            - type: boolean
            - type: string
            - type: number

[Jeeppler]

@ozscheyge thank you for the detailed explanation.

[ozscheyge]

Should be solved with https://github.com/ePages-de/restdocs-api-spec/pull/186

[Jeeppler]

#186 did not solve our problem. Even with: com.epages:restdocs-api-spec-mockmvc:0.16.0. String arrays are not recognized.