描述回應

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

沒有找到您要找的嗎？向社群提問
發現錯誤？請告訴我們