OAS 3 本指南适用于 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请参阅我们的 OpenAPI 2.0 指南.

描述响应

API 规范需要为所有 API 操作指定 responses。每个操作至少要定义一个响应，通常是一个成功的响应。响应由其 HTTP 状态码和响应主体和/或标题中返回的数据定义。以下是一个最小的示例
paths:
  /ping:
    get:
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: pong

响应媒体类型

API 可以使用各种媒体类型进行响应。JSON 是数据交换最常见的格式，但并非唯一可能的格式。要指定响应媒体类型，请在操作级别使用 content 关键字。
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
            application/xml:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
            text/plain:
              schema:
                type: string

  # This operation returns image
  /logo:
    get:
      summary: Get the logo image
      responses:
        '200':
          description: Logo image in PNG format
          content:
            image/png:
              schema:
                type: string
                format: binary
更多信息： 媒体类型.

HTTP 状态码

在 responses 下，每个响应定义都以一个状态码开头，例如 200 或 404。一个操作通常返回一个成功的状态码和一个或多个错误状态。要定义响应代码的范围，您可以使用以下范围定义：1XX、2XX、3XX、4XX 和 5XX。如果使用显式代码定义了响应范围，则显式代码定义优先于该代码的范围定义。每个响应状态都需要一个 description。例如，您可以描述错误响应的条件。Markdown (CommonMark) 可用于富文本表示。
      responses:
        '200':
          description: OK
        '400':
          description: Bad request. User ID must be an integer and larger than 0.
        '401':
          description: Authorization information is missing or invalid.
        '404':
          description: A user with the specified ID was not found.
        '5XX':
          description: Unexpected error.
请注意，API 规范不一定需要涵盖所有可能的 HTTP 响应码，因为它们可能事先未知。但是，它应该涵盖成功的响应和任何已知的错误。“已知错误”是指，例如，对于返回按 ID 查找资源的操作的 404 未找到响应，或者在操作参数无效的情况下为 400 错误请求响应。

响应主体

schema 关键字用于描述响应主体。模式可以定义
  • 一个 object 或一个 array — 通常与 JSON 和 XML API 一起使用，
  • 一个基本数据类型，例如数字或字符串 — 用于纯文本响应，
  • 一个文件 — （见下方）。
模式可以在操作中内联定义
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The user ID.
                  username:
                    type: string
                    description: The user name.
或在全局 components.schemas 部分定义，并通过 $ref 引用。如果多个媒体类型使用相同的模式，这将很有用。
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: The user ID.
        username:
          type: string
          description: The user name.

返回文件的响应

API 操作可以返回一个文件，例如图像或 PDF。OpenAPI 3.0 将文件输入/输出内容定义为 type: string，format: binary 或 format: base64。这与 OpenAPI 2.0 形成对比，后者使用 type: file 来描述文件输入/输出内容。如果响应仅返回文件，您通常会使用二进制字符串模式并为响应 content 指定适当的媒体类型
paths:
  /report:
    get:
      summary: Returns the report in the PDF format
      responses:
        '200':
          description: A PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
文件也可以嵌入到例如 JSON 或 XML 中，作为 base64 编码的字符串。在这种情况下，您将使用类似于
paths:
  /users/me:
    get:
      summary: Returns user information
      responses:
        '200':
          description: A JSON object containing user name and avatar
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                  avatar:          # <-- image embedded into JSON
                    type: string
                    format: byte
                    description: Base64-encoded contents of the avatar image

anyOf，oneOf

OpenAPI 3.0 还支持 oneOf 和 anyOf，因此您可以为响应主体指定备用模式。
      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'

空响应主体

某些响应，例如 204 无内容，没有主体。要指示响应主体为空，请勿为响应指定 content
      responses:
        '204':
          description: The resource was deleted successfully.

响应标题

来自 API 的响应可以包含自定义标题，以提供有关 API 调用的结果的附加信息。例如，受限速率 API 可能会通过响应标题提供限速率状态，如下所示
HTTP 1/1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2016-10-12T11:00:00Z

{ ... }
您可以为每个响应定义自定义 headers，如下所示
paths:
  /ping:
    get:
      summary: Checks if the server is alive.
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per hour.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
              description: The UTC date/time at which the current rate limit window resets.
请注意，目前，OpenAPI 规范不允许为不同的响应代码或不同的 API 操作定义常见的响应标题。您需要为每个响应分别定义标题。

默认响应

有时，操作可以使用不同的 HTTP 状态码返回多个错误，但所有这些错误都具有相同的响应结构
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

        # These two error responses have the same schema
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
您可以使用 default 响应来集体描述这些错误，而不是单独描述。 “默认”意味着此响应用于此操作未单独涵盖的所有 HTTP 代码。
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

        # Definition of all error statuses
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

重用响应

如果多个操作返回相同的响应（状态码和数据），您可以在全局 components 对象的 responses 部分中定义它，然后通过 $ref 在操作级别引用该定义。这对于具有相同状态码和响应主体的错误响应很有用。
paths:
  /users:
    get:
      summary: Gets a list of users.
      response:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
        '401':
          $ref: '#/components/responses/Unauthorized'   # <-----
  /users/{id}:
    get:
      summary: Gets a user by ID.
      response:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'   # <-----
        '404':
          $ref: '#/components/responses/NotFound'       # <-----

# Descriptions of common components
components:
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    # Schema for error response body
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
请注意，在 components.responses 中定义的响应不会自动应用于所有操作。这些只是可以被多个操作引用和重用的定义。响应中的某些值可以用作其他操作的参数。一个典型的例子是“创建资源”操作，它返回创建的资源的 ID，并且此 ID 可用于获取该资源、更新或删除它。OpenAPI 3.0 提供 links 关键字来描述响应和其他 API 调用之间的这种关系。有关更多信息，请参阅 链接.

常见问题解答

我可以根据请求参数获得不同的响应吗？例如 
GET /something -> {200, schema_1}
GET /something?foo=bar -> {200, schema_2}
在 OpenAPI 3.0 中，您可以使用 oneOf 来指定响应的备用模式，并在响应 description 中口头记录可能的依赖项。但是，无法将特定模式链接到特定参数组合。

参考

响应对象

媒体类型对象

组件对象

  

没有找到您要找的内容？ 询问社区
发现错误？ 告诉我们