对象属性 swagger 的多个示例

Question

我正在尝试为对象属性添加多个示例。我使用的 Swagger-Ui 和 Editor 版本是

'{"swaggerEditor":"3.6.31/g10642b3c-dirty","swaggerUi":{"version":"3.23.0","gitRevision":"g23d7260f","gitDirty":true,"buildTimestamp":"Sat, 29 Jun 2019 19:42:59 GMT","machine":"jenins-swagger-oss"}}'

基于OpenAPI doc，此版本的 swagger UI 和编辑器支持多个示例，但我仍然看到此错误：

Structural error at components.schemas.MainObject.allOf.3.properties.partitionProperty
should NOT have additional properties
additionalProperty: examples
Jump to line 3016

这就是我在属性中添加示例的方式：

    MainObject:
      allOf:
      - $ref: '#/components/schemas/MainObjectLite'
      - type: object
        description: foobar.
        readOnly: true
        required:
          - fooRequired
        properties:
         fooRequired:
            type: string
            description: system only field used for table data indexing
         partitionProperty:
            type: string
            description: foobar
            examples:
              sampleExample:
                value: 2016-03-04T03:00:00
                summary: sample partition

Answer 1

开放API 3.0

多个examples仅在媒体类型级别受支持，并且在模式内部不受支持。模式和属性只能有一个example，例如

partitionProperty:
  type: string
  example: '2016-03-04T03:00:00'

换句话说，这是行不通的：

MainObject:
  type: object
  properties:
    ..
  examples:  # <--- Won't work
    minimal:
      summary: Minimal example
      value:
        foo: bar
    full:
      summary: Example with all properties
      value:
        foo: bar
        baz: xyzzy

如果您想要多个examples，则需要使用请求示例或响应示例：

requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/MainObject'
      examples:
        minimal:
          summary: Minimal example
          value:
            foo: bar
        full:
          summary: Example with all properties
          value:
            foo: bar
            baz: xyzzy

开放API 3.1

OAS 3.1 使用较新版本的 JSON Schema，它支持多个examples模式和属性。与媒体类型不同examples，媒体类型是命名示例对象的映射，架构级别和属性级别examples是示例值的简单列表。

MyObject:
  type: object
  properties:
    prop1:
      type: string
      # Property-level examples
      examples:
        - foo
        - bar
    prop2:
      type: integer

  # Object-level examples
  examples:
    - prop1: hello
      prop2: 5
    - prop1: world
      prop2: 0