描述响应

API 规范需要为所有 API 操作指定 responses。每个操作必须至少定义一个响应，通常是一个成功的响应。响应由其 HTTP 状态代码以及在响应正文和/或标头中返回的数据定义。这是一个最小的例子

1
paths:
2
  /ping:
3
    get:
4
      produces:
5
        - application/json
6
      responses:
7
        200:
8
          description: OK

响应媒体类型

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

1
produces:
2
  - application/json
3

4
paths:
5
  # This operation returns JSON - as defined globally above
6
  /users:
7
    get:
8
      summary: Gets a list of users.
9
      responses:
10
        200:
11
          description: OK
12
  # Here, we override the "produces" array to specify other media types
13
  /logo:
14
    get:
15
      summary: Gets the logo image.
16
      produces:
17
        - image/png
18
        - image/gif
19
        - image/jpeg
20
      responses:
21
        200:
22
          description: OK

更多信息： MIME 类型。

HTTP 状态代码

在 responses 下，每个响应定义都以状态代码开头，例如 200 或 404。操作通常返回一个成功的状态代码和一个或多个错误状态。每个响应状态都需要一个 description。例如，您可以描述错误响应的条件。 GitHub Flavored Markdown 可用于富文本表示。

1
responses:
2
  200:
3
    description: OK
4
  400:
5
    description: Bad request. User ID must be an integer and bigger than 0.
6
  401:
7
    description: Authorization information is missing or invalid.
8
  404:
9
    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（请参阅下面）。

模式可以在操作中内联定义

1
responses:
2
  200:
3
    description: A User object
4
    schema:
5
      type: object
6
      properties:
7
        id:
8
          type: integer
9
          description: The user ID.
10
        username:
11
          type: string
12
          description: The user name.

或在根级别定义，并通过 $ref 引用。如果多个响应使用相同的模式，这很有用。

1
      responses:
2
        200:
3
          description: A User object
4
          schema:
5
            $ref: '#/definitions/User'
6
definitions:
7
  User:
8
    type: object
9
    properties:
10
      id:
11
        type: integer
12
        description: The user ID.
13
      username:
14
        type: string
15
        description: The user name.

返回文件的响应

API 操作可以返回一个文件，例如图像或 PDF。在这种情况下，使用 type: file 定义响应 schema，并在 produces 部分中指定适当的 MIME 类型。

1
paths:
2
  /report:
3
    get:
4
      summary: Returns the report in the PDF format.
5
      produces:
6
        - application/pdf
7
      responses:
8
        200:
9
          description: A PDF file.
10
          schema:
11
            type: file

空响应正文

某些响应（如 204 No Content）没有正文。要指示响应正文为空，请不要为响应指定 schema。 Swagger 将没有模式视为没有正文的响应。

1
responses:
2
  204:
3
    description: The resource was deleted successfully.

响应标头

来自 API 的响应可以包含自定义标头，以提供有关 API 调用结果的附加信息。例如，速率限制的 API 可以通过响应标头提供速率限制状态，如下所示

1
HTTP 1/1 200 OK
2
X-RateLimit-Limit: 100
3
X-RateLimit-Remaining: 99
4
X-RateLimit-Reset: 2016-10-12T11:00:00Z
5

6
{ ... }

您可以为每个响应定义自定义 headers，如下所示

1
paths:
2
  /ping:
3
    get:
4
      summary: Checks if the server is alive.
5
      responses:
6
        200:
7
          description: OK
8
          headers:
9
            X-RateLimit-Limit:
10
              type: integer
11
              description: Request limit per hour.
12
            X-RateLimit-Remaining:
13
              type: integer
14
              description: The number of requests left for the time window.
15
            X-RateLimit-Reset:
16
              type: string
17
              format: date-time
18
              description: The UTC date/time at which the current rate limit window resets.

请注意，目前，Swagger 中无法为不同的响应代码或不同的 API 操作定义通用的响应标头。您需要单独为每个响应定义标头。

默认响应

有时，一个操作可能会返回具有不同 HTTP 状态代码的多个错误，但所有这些错误都具有相同的响应结构

1
responses:
2
  200:
3
    description: Success
4
    schema:
5
      $ref: "#/definitions/User"
6
  400:
7
    description: Bad request
8
    schema:
9
      $ref: "#/definitions/Error" # <-----
10
  404:
11
    description: Not found
12
    schema:
13
      $ref: "#/definitions/Error" # <-----

您可以使用 default 响应来集体描述这些错误，而不是单独描述。 “默认”表示此响应用于此操作未单独涵盖的所有 HTTP 代码。

1
responses:
2
  200:
3
    description: Success
4
    schema:
5
      $ref: "#/definitions/User"
6
  # Definition of all error statuses
7
  default:
8
    description: Unexpected error
9
    schema:
10
      $ref: "#/definitions/Error"

重用响应

如果多个操作返回相同的响应（状态代码和数据），您可以在全局 responses 部分中定义它，并通过操作级别的 $ref 引用该定义。这对于具有相同状态代码和响应正文的错误响应很有用。

1
paths:
2
  /users:
3
    get:
4
      summary: Gets a list of users.
5
      response:
6
        200:
7
          description: OK
8
          schema:
9
            $ref: "#/definitions/ArrayOfUsers"
10
        401:
11
          $ref: "#/responses/Unauthorized" # <-----
12
  /users/{id}:
13
    get:
14
      summary: Gets a user by ID.
15
      response:
16
        200:
17
          description: OK
18
          schema:
19
            $ref: "#/definitions/User"
20
        401:
21
          $ref: "#/responses/Unauthorized" # <-----
22
        404:
23
          $ref: "#/responses/NotFound" # <-----
24
# Descriptions of common responses
25
responses:
26
  NotFound:
27
    description: The specified resource was not found
28
    schema:
29
      $ref: "#/definitions/Error"
30
  Unauthorized:
31
    description: Unauthorized
32
    schema:
33
      $ref: "#/definitions/Error"
34
definitions:
35
  # Schema for error response body
36
  Error:
37
    type: object
38
    properties:
39
      code:
40
        type: string
41
      message:
42
        type: string
43
    required:
44
      - code
45
      - message

请注意，在根级别定义的响应不会自动应用于所有操作。这些只是可以被多个操作引用和重用的定义。

常见问题

我可以根据请求参数获得不同的响应吗？比如

1
GET /something -> {200, schema_1}
2
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

没有找到您要找的东西？请咨询社区
发现错误？请告诉我们