跳到内容

描述响应

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。在这种情况下，请将响应schema定义为type: file，并在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响应来集体描述这些错误，而不是单独描述。“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

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

© . All rights reserved.