Swagger 使用相同的模型但不同的示例

Question

我的 API 可以返回 200 ok 或 400，发生错误。我希望他们都使用相同的模型，但使用不同的示例。在下面的代码中，我希望我的 200 信息说“一切正常”和 400 的信息“不正常”。

 responses:
        '200':
          description: >-
            Invoice received for processing but beware of potentional warnings
            and information
          schema:
            $ref: '#/definitions/Response'
        '400':
          description: Invoice could not be processed due to fatal errors
          schema:
            $ref: '#/definitions/Response'

  Response:
    type: object
    properties:
      Info:
        type: string
          information
      Messages:
        type: object
        properties:
          Fatal:
            type: array
            items:
              type: object
          Warning:
            type: array
            items:
              type: object
          Information:
            type: array
            items:
              type: object

Answer 1

在 OpenAPI 2.0 中，响应支持 examples 关键字来指定不同 HTTP 状态代码和媒体类型的响应示例。

      responses:
        '200':
          description: >-
            Invoice received for processing but beware of potential warnings
            and information
          schema:
            $ref: '#/definitions/Response'
          examples:
            application/json:
              Info: OK
            # Or using JSON syntax for the example value:
            # application/json: {"Info": "OK"}

        '400':
          description: Invoice could not be processed due to fatal errors
          schema:
            $ref: '#/definitions/Response'
          examples:
            application/json:
              Info: Oops
              Messages:
                Fatal:
                  - Houston, we have a problem
            # Or using JSON syntax for the example value:
            # application/json:
            #   {
            #     "Info": "Oops",
            #     "Messages": [
            #       {
            #         "Fatal": [
            #           {"Custom error": "Houston, we have a problem"}
            #         ]
            #       }
            #     ]
            #   }