FieldDescriptor optional() is not working

[traeper]

Hello.
I'm gratefully use restdocs-api-spec in my company.

Overall, it seems that the API specification is well generated. However, even if the FieldDescriptor entering the requestFields/responseFields is written to perform optional(), the generated yml file does not display the optional value.

Could you please tell me how to display the nullable value in requestFields/responseFields

Thanks in advance.

[traeper]

I found ConstrainedFields that may fix my issue.
Thanks. :D

[ozscheyge]

Hey!

optional() should work even for regular FieldDescriptors. Which target format are you generating?

[traeper]

@ozscheyge

I want to generate 'nullable' property.
API RequestBody data object has nullable value. (metadata)

• library : com.epages:restdocs-api-spec-mockmvc:0.10.3

• mockMvc test code

mockMvc.perform(
            post("/api/v1/test")
                .param("transaction_id", transactionId)
                .contentType(MediaType.APPLICATION_JSON)
                .content(json)
        )
            .andExpect(status().isOk)
            .andExpect(content().contentType(MediaType.APPLICATION_JSON))
            .andDo(
                MockMvcRestDocumentationWrapper.document(
                    "test/{methodName}",
                    requestParameters(requestParameterDescriptors()),
                    requestFields(requestFieldDescriptors()),
                    responseFields(responseFieldDescriptors())
                )
            )

• private descriptors codes

    private fun requestParameterDescriptors(): List<ParameterDescriptor> = listOf(
        parameterWithName("transaction_id").description("transaction id")
    )

    private fun requestFieldDescriptors(): List<FieldDescriptor> =
        listOf(
            fieldWithPath("number1").type(JsonFieldType.STRING).description("desc"),
            fieldWithPath("number2").type(JsonFieldType.STRING).description("desc"),
            fieldWithPath("type").type(JsonFieldType.STRING).description("desc"),
            fieldWithPath("content").type(JsonFieldType.STRING).description("desc"),
            fieldWithPath("metadata").type(JsonFieldType.STRING).description("desc").optional(),
        )

    private fun responseFieldDescriptors(): List<FieldDescriptor> = listOf(
        fieldWithPath("transaction_id").type(JsonFieldType.STRING)
            .description("transaction id")
    )

the result of yml file is below.
metadata is not optional (I need to generate nullable = true or required = false)

components:
  schemas:
    api-v1-test-hmac793873085:
      type: object
      properties:
        metadata:
          type: string
          description: desc
        number2:
          type: string
          description: desc
        number1:
          type: string
          description: desc
        type:
          type: string
          description: desc
        content:
          type: string
          description: desc

[traeper]

When add optional() to parameterWithName("transaction_id").description("transaction id") in requestParameterDescriptors() method, result of yml file added required: false correctly

parameters:
      - name: transaction_id
        in: query
        description: desc
        required: true
        schema:
          type: string

but.. components.schemas.properties.. required is not showing.

[ozscheyge]

Thanks for the additional info @traeper !

I could reproduce the issue for both OpenAPI 2 and OpenAPI 3 generators. The info is correctly gathered in resource.json snippet from the descriptors, but not utilized by the OpenAPI generators. So far, we seem to only value the optional for ParameterDescriptors.

How it should look like (required property in the schema object with an array of required fields, same level as properties):
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#schema-object-examples
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object-examples
https://tools.ietf.org/html/draft-wright-json-schema-validation-00#section-5.15

[ozscheyge]

Seems to be a duplicate of #90

[ozscheyge]

Should be fixed with #183

[GoodGoodJM]

When can we use the version which this issue has been resolved? Is there a scheduled date?

[ooz]

When can we use the version which this issue has been resolved? Is there a scheduled date?

Hey @GoodGoodJM ,
I hoped to resolve another issue with the same release, but it isn't moving, so I'll release a new version now, ETA in 1h.

Sorry for the inconvenience!