コンテンツにスキップ

レスポンスの記述

API 仕様では、すべての API 操作の `responses` を指定する必要があります。各操作には、通常は成功レスポンスとして、少なくとも1つのレスポンスが定義されている必要があります。レスポンスは、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 などのステータスコードで始まります。操作は通常、1つの成功ステータスコードと1つ以上のエラー状態を返します。レスポンスコードの範囲を定義するには、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` キーワードは、レスポンスボディを記述するために使用されます。スキーマは次を定義できます。

  • オブジェクトまたは配列 — 通常、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` として定義します。これは、ファイル入力/出力コンテンツを記述するために `type: file` を使用する OpenAPI 2.0 とは対照的です。レスポンスがファイルのみを返す場合は、通常、バイナリ文字列スキーマを使用し、レスポンス `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 Specification では、異なるレスポンスコードや異なる 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` レスポンスを使用できます。「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 は、レスポンスと他の API 呼び出しとの間のそのような関係を記述するために `links` キーワードを提供します。詳細については、リンクを参照してください。

FAQ

リクエストパラメータに基づいて異なるレスポンスを持つことはできますか？たとえば、

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

OpenAPI 3.0 では、`oneOf` を使用してレスポンスの代替スキーマを指定し、レスポンス `description` で考えられる依存関係を口頭で文書化できます。ただし、特定のスキーマを特定のパラメータの組み合わせにリンクする方法はありません。

参照

レスポンスオブジェクト

MediaType オブジェクト

コンポーネントオブジェクト

お探しのものが見つかりませんでしたか？ コミュニティに質問する
間違いを見つけましたか？ お知らせください