Swagger 2.0 Yaml 中的多个请求示例答案

【问题标题】：Multiple Request Examples in Swagger 2.0 YamlSwagger 2.0 Yaml 中的多个请求示例
【发布时间】：2021-06-04 14:59:49
【问题描述】：

我有一个 API，它有一些针对 json 有效负载的互斥参数。我想在多个示例中显示这一点，但 yaml 文件中的schema 似乎只能生成一个示例。

如果我的输入可以是：

{
  "text": "some text"
}

或

{
  "list": ["some text", "some more"]
}

但不是

{
  "text": "some text",
  "list": ["some text", "some more"]
}

如何在 swagger 2.0 中做到这一点？

类似以下的架构定义具有误导性

definitions:
  MutexSchema:
    type: object
    properties:
      list:
        type: array
        items:
          type: string
        example: ["some text", "some more"]
      text:
        type: string
        example: "Some text"

而且您似乎不能指定多个body 选项。显示互斥有效负载及其相应响应的好方法是什么？

【问题讨论】：

标签： swagger openapi swagger-2.0

【解决方案1】：

OpenAPI 2.0 不支持互斥属性，但您可以通过将 minProperties: 1 和 maxProperties: 1 添加到架构中来模拟这一点。这实质上意味着只能传递text 或仅list，但不能同时传递两者。

definitions:
  MutexSchema:
    type: object
    properties:
      list:
        type: array
        items:
          type: string
        example: ["some text", "some more"]
      text:
        type: string
        example: "Some text"
    minProperties: 1   # <--------
    maxProperties: 1

显示互斥有效负载及其相应响应的好方法是什么？

迁移到支持oneOf 和multiple examples 的请求和响应的OpenAPI 3。请注意，无法关联请求和响应示例，但您可以在 description 字段中提供更多信息。

paths:
  /something:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MutexSchema'

            # Request body examples
            examples:
              text example:
                summary: Example with text
                value:
                  text: Some text
              list example:
                summary: Example with list
                value:
                  list: [some text, some more]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                ...

              # Response examples
              examples:
                ex1:
                  summary: ...
                  value:
                    ...
                ex2:
                  summary: ...
                  value:
                    ...

components:
  schemas:
    MutexSchema:
      oneOf:
        - $ref: '#/components/schemas/Text'
        - $ref: '#/components/schemas/List'

    Text:
      type: object
      required:
        - text     # <--- Property must be marked as required for oneOf to work
      properties:
        text:
          type: string
          example: Some text
      additionalProperties: false

    List:
      type: object
      required:
        - list     # <--- Property must be marked as required for oneOf to work
      properties:
        list:
          type: array
          items:
            type: string
          example: [some text, some more]
      additionalProperties: false

【讨论】：