Swagger 2.0 Yaml 中的多个请求示例

Question

我有一个 API 有一些相互排斥的 arguments 用于 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选项。 什么是显示互斥有效负载及其相应响应的好方法？

Answer 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和多个请求和响应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