OpenAPI 3 lost schema properties required list.

[abcfy2]

Here is the snippet from require.json:

  "response" : {
    "status" : 200,
    "contentType" : "application/json",
    "headers" : [ ],
    "responseFields" : [ {
      "attributes" : { },
      "description" : "OSS的access key id",
      "ignored" : false,
      "path" : "accessKeyId",
      "type" : "STRING",
      "optional" : false
    }, {
      "attributes" : { },
      "description" : "OSS的权限矩阵",
      "ignored" : false,
      "path" : "policy",
      "type" : "STRING",
      "optional" : false
    }, {
      "attributes" : { },
      "description" : "OSS认证成功后的签名",
      "ignored" : false,
      "path" : "signature",
      "type" : "STRING",
      "optional" : false
    }, {
      "attributes" : { },
      "description" : "有权限上传的目录",
      "ignored" : false,
      "path" : "dir",
      "type" : "STRING",
      "optional" : false
    }, {
      "attributes" : { },
      "description" : "OSS访问主机",
      "ignored" : false,
      "path" : "host",
      "type" : "STRING",
      "optional" : false
    }, {
      "attributes" : { },
      "description" : "授权过期时间",
      "ignored" : false,
      "path" : "expire",
      "type" : "NUMBER",
      "optional" : false
    }, {
      "attributes" : { },
      "description" : "用于外部访问的CDN URL(可空)",
      "ignored" : false,
      "path" : "cdnUrl",
      "type" : "STRING",
      "optional" : true
    } ],

But convert to openapi3.yaml lost the optional field:

components:
  schemas:
    api-getUploadAuthority2026114897:
      type: object
      properties:
        accessKeyId:
          type: string
          description: OSS的access key id
        signature:
          type: string
          description: OSS认证成功后的签名
        cdnUrl:
          type: string
          description: 用于外部访问的CDN URL(可空)
        expire:
          type: number
          description: 授权过期时间
        host:
          type: string
          description: OSS访问主机
        dir:
          type: string
          description: 有权限上传的目录
        policy:
          type: string
          description: OSS的权限矩阵

OpenAPI 3 has required property list. See: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schema-object

I hope optional from resource.json could render to required to openapi3.yaml.

components:
  schemas:
    api-getUploadAuthority2026114897:
      type: object
      required:                  # <======== Add required list except isOptioanl() is true
        - accessKeyId
        - signature
        - expire
        - host
        - dir
        - policy
      properties:
        accessKeyId:
          type: string
          description: OSS的access key id
        signature:
          type: string
          description: OSS认证成功后的签名
        cdnUrl:
          type: string
          description: 用于外部访问的CDN URL(可空)
        expire:
          type: number
          description: 授权过期时间
        host:
          type: string
          description: OSS访问主机
        dir:
          type: string
          description: 有权限上传的目录
        policy:
          type: string
          description: OSS的权限矩阵

[mduesterhoeft]

This sounds like a very reasonable suggestion. No idea why we did not do it from the beginning. Any doubts @ozscheyge?

[ozscheyge]

Yeah, looks like an error, in the generation of the openapi 2 spec, we do exactly this!

[mduesterhoeft]

Strange - we use the same JsonSchema generator for openApi 2 and 3.

[mduesterhoeft]

At the moment the required property in the schema is set by introspecting bean validation constraints - https://github.com/ePages-de/restdocs-api-spec#documenting-bean-validation-constraints

We do not look at the optional field in the field descriptor. The question is, if we should do this.

See also https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-jsonschema/src/main/kotlin/com/epages/restdocs/apispec/jsonschema/JsonSchemaFromFieldDescriptorsGenerator.kt#L162