描述响应

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"

重用响应

如果多个操作返回相同的响应（状态代码和数据），您可以在全局 components 对象的 responses 部分中定义它，然后在操作级别通过 $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 中以文字形式记录可能的依赖关系。但是，没有办法将特定模式链接到特定的参数组合。

参考

响应对象

MediaType 对象

组件对象

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