跳到内容

描述响应

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

1
paths:
2
  /ping:
3
    get:
4
      responses:
5
        "200":
6
          description: OK
7
          content:
8
            text/plain:
9
              schema:
10
                type: string
11
                example: pong

响应媒体类型

API 可以响应各种媒体类型。JSON 是数据交换最常见的格式，但并非唯一可能。要指定响应媒体类型，请在操作级别使用content 关键词。

1
paths:
2
  /users:
3
    get:
4
      summary: Get all users
5
      responses:
6
        "200":
7
          description: A list of users
8
          content:
9
            application/json:
10
              schema:
11
                $ref: "#/components/schemas/ArrayOfUsers"
12
            application/xml:
13
              schema:
14
                $ref: "#/components/schemas/ArrayOfUsers"
15
            text/plain:
16
              schema:
17
                type: string
18


19
  # This operation returns image
20
  /logo:
21
    get:
22
      summary: Get the logo image
23
      responses:
24
        "200":
25
          description: Logo image in PNG format
26
          content:
27
            image/png:
28
              schema:
29
                type: string
30
                format: binary

更多信息： 媒体类型。

HTTP 状态码

在responses 下，每个响应定义都以状态码开头，例如 200 或 404。操作通常返回一个成功状态码和一个或多个错误状态。要定义响应代码范围，您可以使用以下范围定义：1XX、2XX、3XX、4XX 和 5XX。如果使用显式代码定义响应范围，则显式代码定义优先于该代码的范围定义。每个响应状态都需要一个description。例如，您可以描述错误响应的条件。Markdown (CommonMark) 可用于富文本表示。

1
responses:
2
  "200":
3
    description: OK
4
  "400":
5
    description: Bad request. User ID must be an integer and larger 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.
10
  "5XX":
11
    description: Unexpected error.

请注意，API 规范不一定需要涵盖所有可能的 HTTP 响应代码，因为它们可能无法预先得知。然而，它应该涵盖成功响应和任何已知错误。我们所说的“已知错误”是指，例如，对于通过 ID 返回资源的操作的 404 Not Found 响应，或在操作参数无效情况下的 400 Bad Request 响应。

响应体

“schema”关键词用于描述响应体。模式可以定义

  • 一个object”或一个array”——通常与 JSON 和 XML API 一起使用，
  • 一个原始数据类型，例如数字或字符串——用于纯文本响应，
  • 一个文件——（参见下文）。

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

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

或在全局components.schemas”部分定义并通过$ref”引用。如果多个媒体类型使用相同的模式，这将很有用。

1
responses:
2
  "200":
3
    description: A User object
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8
    components:
9
      schemas:
10
        User:
11
          type: object
12
          properties:
13
            id:
14
              type: integer
15
              description: The user ID.
16
            username:
17
              type: string
18
              description: The user name.

返回文件的响应

API 操作可以返回文件，例如图像或 PDF。OpenAPI 3.0 将文件输入/输出内容定义为type: string”并带有format: binary”或format: base64”。这与 OpenAPI 2.0 不同，OpenAPI 2.0 使用type: file”来描述文件输入/输出内容。如果响应仅返回文件，您通常会使用二进制字符串模式并为响应指定适当的媒体类型content

1
paths:
2
  /report:
3
    get:
4
      summary: Returns the report in the PDF format
5
      responses:
6
        "200":
7
          description: A PDF file
8
          content:
9
            application/pdf:
10
              schema:
11
                type: string
12
                format: binary

文件也可以作为 base64 编码的字符串嵌入到（例如）JSON 或 XML 中。在这种情况下，您会使用类似这样的内容

1
paths:
2
  /users/me:
3
    get:
4
      summary: Returns user information
5
      responses:
6
        "200":
7
          description: A JSON object containing user name and avatar
8
          content:
9
            application/json:
10
              schema:
11
                type: object
12
                properties:
13
                  username:
14
                    type: string
15
                  avatar: # <-- image embedded into JSON
16
                    type: string
17
                    format: byte
18
                    description: Base64-encoded contents of the avatar image

anyOf, oneOf

OpenAPI 3.0 还支持oneOf”和anyOf”，因此您可以为响应体指定替代模式。

1
responses:
2
  "200":
3
    description: A JSON object containing pet information
4
    content:
5
      application/json:
6
        schema:
7
          oneOf:
8
            - $ref: "#/components/schemas/Cat"
9
            - $ref: "#/components/schemas/Dog"
10
            - $ref: "#/components/schemas/Hamster"

空响应体

某些响应（例如 204 No Content）没有响应体。要指示响应体为空，请不要为响应指定content

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
              schema:
11
                type: integer
12
              description: Request limit per hour.
13
            X-RateLimit-Remaining:
14
              schema:
15
                type: integer
16
              description: The number of requests left for the time window.
17
            X-RateLimit-Reset:
18
              schema:
19
                type: string
20
                format: date-time
21
              description: The UTC date/time at which the current rate limit window resets.

请注意，目前 OpenAPI 规范不允许为不同的响应代码或不同的 API 操作定义通用响应头。您需要为每个响应单独定义响应头。

默认响应

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

1
responses:
2
  "200":
3
    description: Success
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8


9
  # These two error responses have the same schema
10
  "400":
11
    description: Bad request
12
    content:
13
      application/json:
14
        schema:
15
          $ref: "#/components/schemas/Error"
16
  "404":
17
    description: Not found
18
    content:
19
      application/json:
20
        schema:
21
          $ref: "#/components/schemas/Error"

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

1
responses:
2
  "200":
3
    description: Success
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8


9
  # Definition of all error statuses
10
  default:
11
    description: Unexpected error
12
    content:
13
      application/json:
14
        schema:
15
          $ref: "#/components/schemas/Error"

复用响应

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

1
paths:
2
  /users:
3
    get:
4
      summary: Gets a list of users.
5
      response:
6
        "200":
7
          description: OK
8
          content:
9
            application/json:
10
              schema:
11
                $ref: "#/components/schemas/ArrayOfUsers"
12
        "401":
13
          $ref: "#/components/responses/Unauthorized" # <-----
14
  /users/{id}:
15
    get:
16
      summary: Gets a user by ID.
17
      response:
18
        "200":
19
          description: OK
20
          content:
21
            application/json:
22
              schema:
23
                $ref: "#/components/schemas/User"
24
        "401":
25
          $ref: "#/components/responses/Unauthorized" # <-----
26
        "404":
27
          $ref: "#/components/responses/NotFound" # <-----
28


29
# Descriptions of common components
30
components:
31
  responses:
32
    NotFound:
33
      description: The specified resource was not found
34
      content:
35
        application/json:
36
          schema:
37
            $ref: "#/components/schemas/Error"
38
    Unauthorized:
39
      description: Unauthorized
40
      content:
41
        application/json:
42
          schema:
43
            $ref: "#/components/schemas/Error"
44


45
  schemas:
46
    # Schema for error response body
47
    Error:
48
      type: object
49
      properties:
50
        code:
51
          type: string
52
        message:
53
          type: string
54
      required:
55
        - code
56
        - message

请注意，在components.responses”中定义的响应不会自动应用于所有操作。这些只是可以被多个操作引用和复用的定义。

将响应值链接到其他操作

响应中的某些值可以用作其他操作的参数。一个典型例子是“创建资源”操作，它返回所创建资源的 ID，并且此 ID 可用于获取、更新或删除该资源。OpenAPI 3.0 提供了links”关键词来描述响应与其他 API 调用之间的此类关系。更多信息，请参见链接。

常见问题

我能否根据请求参数获得不同的响应？例如

1
GET /something -> {200, schema_1}
2
GET /something?foo=bar -> {200, schema_2}

在 OpenAPI 3.0 中，您可以使用oneOf”为响应指定替代模式，并在响应description”中口头记录可能的依赖关系。但是，没有办法将特定模式链接到某些参数组合。

参考

响应对象

媒体类型对象

组件对象

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

© . All rights reserved.