OAS 2 此页面适用于 OpenAPI 规范 v2（以前称为 Swagger）。要了解最新版本，请访问 OpenAPI 3 页面。

描述响应

API 规范需要为所有 API 操作指定 responses。每个操作必须至少定义一个响应，通常是一个成功的响应。响应由其 HTTP 状态码以及响应主体和/或头中返回的数据定义。以下是一个最小的示例
paths:
  /ping:
    get:
      produces:
        - application/json
      responses:
        200:
          description: OK

响应媒体类型

API 可以使用各种媒体类型进行响应。JSON 是数据交换最常见的格式，但并非唯一可能的格式。要指定响应媒体类型，请在根级别或操作级别使用 produces 关键字。全局列表可以在操作级别覆盖。
produces:
  - application/json

paths:
  # This operation returns JSON - as defined globally above
  /users:
    get:
      summary: Gets a list of users.
      responses:
        200:
          description: OK
  # Here, we override the "produces" array to specify other media types
  /logo:
    get:
      summary: Gets the logo image.
      produces:
        - image/png
        - image/gif
        - image/jpeg
      responses:
        200:
          description: OK
更多信息： MIME 类型。

HTTP 状态码

在 responses 下，每个响应定义都以状态码开头，例如 200 或 404。操作通常返回一个成功状态码和一个或多个错误状态。每个响应状态都需要一个 description。例如，您可以描述错误响应的条件。 GitHub 风格的 Markdown 可用于富文本表示。
      responses:
        200:
          description: OK
        400:
          description: Bad request. User ID must be an integer and bigger than 0.
        401:
          description: Authorization information is missing or invalid.
        404:
          description: A user with the specified ID was not found.
请注意，API 规范不一定需要涵盖所有可能的 HTTP 响应代码，因为它们可能无法预先知道。但是，预期它涵盖成功的响应和任何已知的错误。通过“已知错误”，我们指的是例如，对于通过 ID 返回资源的操作的 404 Not Found 响应，或者在操作参数无效时出现的 400 Bad Request 响应。

响应主体

schema 关键字用于描述响应主体。模式可以定义
  • object 或 array - 通常与 JSON 和 XML API 一起使用，
  • 原始类型（如数字或字符串） - 用于纯文本响应，
  • file（参见 下方）。
模式可以在操作中内联定义
      responses:
        200:
          description: A User object
          schema:
            type: object
            properties:
              id:
                type: integer
                description: The user ID.
              username:
                type: string
                description: The user name.
或在根级别定义并通过 $ref 引用。如果多个响应使用相同的模式，这很有用。
      responses:
        200:
          description: A User object
          schema:
            $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        description: The user ID.
      username:
        type: string
        description: The user name.

返回文件的响应

API 操作可以返回文件，例如图像或 PDF。在这种情况下，使用 type: file 定义响应 schema，并在 produces 部分中指定适当的 MIME 类型。
paths:
  /report:
    get:
      summary: Returns the report in the PDF format.
      produces:
        - application/pdf
      responses:
        200:
          description: A PDF file.
          schema:
            type: file

空的响应主体

某些响应（例如 204 No Content）没有主体。要指示响应主体为空，请不要为响应指定 schema。Swagger 将没有模式视为没有主体的响应。
      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:
              type: integer
              description: Request limit per hour.
            X-RateLimit-Remaining:
              type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              type: string
              format: date-time
              description: The UTC date/time at which the current rate limit window resets.
请注意，目前，在 Swagger 中无法为不同的响应代码或不同的 API 操作定义常见的响应头。您需要为每个响应单独定义头。

默认响应

有时，操作可以使用不同的 HTTP 状态码返回多个错误，但它们都具有相同的响应结构
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/User'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'    # <-----
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'    # <-----
您可以使用 default 响应来集体描述这些错误，而不是单独描述。 “默认”表示此响应用于未为此操作单独覆盖的所有 HTTP 代码。
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/User'
        # Definition of all error statuses
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

重用响应

如果多个操作返回相同的响应（状态码和数据），您可以在全局 responses 部分中定义它，并在操作级别通过 $ref 引用该定义。这对具有相同状态码和响应主体的错误响应很有用。
paths:
  /users:
    get:
      summary: Gets a list of users.
      response:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ArrayOfUsers'
        401:
          $ref: '#/responses/Unauthorized'   # <-----
  /users/{id}:
    get:
      summary: Gets a user by ID.
      response:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
        401:
          $ref: '#/responses/Unauthorized'   # <-----
        404:
          $ref: '#/responses/NotFound'       # <-----
# Descriptions of common responses
responses:
  NotFound:
    description: The specified resource was not found
    schema:
      $ref: '#/definitions/Error'
  Unauthorized:
    description: Unauthorized
    schema:
      $ref: '#/definitions/Error'
definitions:
  # Schema for error response body
  Error:
    type: object
    properties:
      code:
        type: string
      message:
        type: string
    required:
      - code
      - message
请注意，在根级别定义的响应不会自动应用于所有操作。这些只是可以被多个操作引用和重用的定义。

常见问题解答

我可以根据请求参数拥有不同的响应吗？例如 
GET /something -> {200, schema_1}
GET /something?foo=bar -> {200, schema_2}
不，不支持。

参考

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesDefinitionsObject

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesObject

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject

  

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