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