コンテンツにスキップ

レスポンスの記述

API仕様は、すべてのAPI操作に対してresponsesを指定する必要があります。各操作には、少なくとも1つのレスポンス（通常は成功レスポンス）が定義されている必要があります。レスポンスは、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などのステータスコードから始まります。操作は通常、1つの成功ステータスコードと1つ以上のエラー状態を返します。各レスポンスステータスには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などのファイルを返すことができます。この場合、schemaをtype: fileで定義し、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

ルートレベルで定義されたレスポンスは、すべての操作に自動的に適用されるわけではないことに注意してください。これらは、複数の操作で参照および再利用できる定義にすぎません。

FAQ

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

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

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