跳至內容

描述回應

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

檔案也可以嵌入到 JSON 或 XML 中，作為 base64 編碼的字串。在這種情況下，您會使用類似下列的語法

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 中以口頭方式記錄可能的相依性。但是，沒有辦法將特定綱要連結到特定的參數組合。

參考

回應物件

媒體類型物件

元件物件

沒有找到您要尋找的內容？詢問社群
發現錯誤？讓我們知道

Swagger 開源
Swagger
專業工具
資源