有没有办法在 OpenAPI 3.0 中描述两种不同的响应类型？

Posted 2023-03-15

【中文标题】有没有办法在 OpenAPI 3.0 中描述两种不同的响应类型？

【英文标题】：Is there a way to describe two different response types in OpenAPI 3.0?

【发布时间】：2018-10-28 01:48:06

【问题描述】：

我想做的是指定有时对 API 调用的响应可能是 PDF 文档，有时是 JSON。我想以 OpenAPI 3.0 格式执行此操作。对于 PDF，响应如下所示：

      responses:
        '200':
          description: An invoice in PDF format.
          content:
            application/pdf:
              schema:
                type: string
                format: binary

在 JSON 响应的情况下，这将描述响应：

      responses:
        '200':
          description: A JSON object containing user name and avatar
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice" 

OAS3 文档 (https://swagger.io/docs/specification/describing-responses/) 提供了以下示例，说明如何指定几种不同 JSON 模式之一可能是对特定 API 调用的响应。这几乎是我想要的，除了描述不同的可能 JSON 模式之外，我想指定不同的可能内容类型，如上所述。有没有办法以 OAS3 格式执行此操作？

      responses:
        '200':
          description: A JSON object containing pet information
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Cat'
                  - $ref: '#/components/schemas/Dog'
                  - $ref: '#/components/schemas/Hamster'

【参考方案1】：

刚刚发现这行得通：

responses:
    '200':
      description: "An invoice."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Invoice"
        application/pdf:
          schema:
            type: "string"
            format: "binary"

请参阅此处的“响应媒体类型”部分：https://swagger.io/docs/specification/describing-responses/