OAS 2 このページは OpenAPI 仕様バージョン 2（旧 Swagger）に適用されます。最新バージョンについては、OpenAPI 3 のページをご覧ください。
レスポンスの説明
API 仕様では、すべての API 操作に対する
responses を指定する必要があります。各操作には、少なくとも 1 つのレスポンス、通常は成功レスポンスが定義されている必要があります。レスポンスは、その HTTP ステータスコードと、レスポンスボディおよび/またはヘッダーで返されるデータによって定義されます。最小限の例を次に示します。
paths:
/ping:
get:
produces:
- application/json
responses:
200:
description: OK
レスポンスのメディアタイプ
API はさまざまなメディアタイプで応答できます。JSON はデータ交換に最も一般的な形式ですが、それだけではありません。レスポンスのメディアタイプを指定するには、ルートレベルまたは操作レベルで
produces キーワードを使用します。グローバルリストは、操作レベルでオーバーライドできます。
produces:
- application/json
paths:
# This operation returns JSON - as defined globally above
/users:
get:
summary: Gets a list of users.
responses:
200:
description: OK
# Here, we override the "produces" array to specify other media types
/logo:
get:
summary: Gets the logo image.
produces:
- image/png
- image/gif
- image/jpeg
responses:
200:
description: OK
詳細: MIME タイプ。
HTTP ステータスコード
responses の下で、各レスポンス定義は、200 や 404 などのステータスコードで始まります。操作は通常、1 つの成功ステータスコードと、1 つ以上のエラーステータスを返します。各レスポンスステータスには
description が必要です。たとえば、エラーレスポンスの条件を記述できます。
GitHub Flavored Markdown を使用して、リッチテキスト表現を使用できます。
responses:
200:
description: OK
400:
description: Bad request. User ID must be an integer and bigger than 0.
401:
description: Authorization information is missing or invalid.
404:
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（下記を参照）。
スキーマは、操作内でインラインで定義できます
responses:
200:
description: A User object
schema:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
またはルートレベルで定義し、
$ref を介して参照できます。これは、複数のレスポンスが同じスキーマを使用する場合に便利です。
responses:
200:
description: A User object
schema:
$ref: '#/definitions/User'
definitions:
User:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
ファイルを返すレスポンス
API 操作は、画像や PDF などのファイルを返すことができます。この場合、
type: file でレスポンスの
schema を定義し、
produces セクションで適切な MIME タイプを指定します。
paths:
/report:
get:
summary: Returns the report in the PDF format.
produces:
- application/pdf
responses:
200:
description: A PDF file.
schema:
type: file
空のレスポンスボディ
204 No Content など、一部のレスポンスにはボディがありません。レスポンスボディが空であることを示すには、レスポンスの
schema を指定しないでください。Swagger は、スキーマがない場合、ボディのないレスポンスとして扱います。
responses:
204:
description: The resource was deleted successfully.
API からのレスポンスには、API 呼び出しの結果に関する追加情報を提供するためのカスタムヘッダーを含めることができます。たとえば、レート制限のある API は、次のようにレスポンスヘッダーを介してレート制限ステータスを提供できます。
HTTP 1/1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2016-10-12T11:00:00Z
{ ... }
次のように、各レスポンスにカスタム
headers を定義できます。
paths:
/ping:
get:
summary: Checks if the server is alive.
responses:
200:
description: OK
headers:
X-RateLimit-Limit:
type: integer
description: Request limit per hour.
X-RateLimit-Remaining:
type: integer
description: The number of requests left for the time window.
X-RateLimit-Reset:
type: string
format: date-time
description: The UTC date/time at which the current rate limit window resets.
現在、Swagger では、異なるレスポンスコードや異なる API 操作に対して共通のレスポンスヘッダーを定義する方法がないことに注意してください。各レスポンスに対してヘッダーを個別に定義する必要があります。
デフォルトレスポンス
場合によっては、操作が異なる HTTP ステータスコードで複数のエラーを返す可能性がありますが、それらはすべて同じレスポンス構造を持っています
responses:
200:
description: Success
schema:
$ref: '#/definitions/User'
400:
description: Bad request
schema:
$ref: '#/definitions/Error' # <-----
404:
description: Not found
schema:
$ref: '#/definitions/Error' # <-----
default レスポンスを使用して、これらのエラーを個別にではなく、まとめて記述できます。「デフォルト」とは、このレスポンスが、この操作に対して個別に網羅されていないすべての HTTP コードに使用されることを意味します。
responses:
200:
description: Success
schema:
$ref: '#/definitions/User'
# Definition of all error statuses
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
レスポンスの再利用
複数の操作が同じレスポンス（ステータスコードとデータ）を返す場合は、グローバルな
responses セクションでそれを定義し、操作レベルで
$ref を介してその定義を参照できます。これは、同じステータスコードとレスポンスボディを持つエラーレスポンスに役立ちます。
paths:
/users:
get:
summary: Gets a list of users.
response:
200:
description: OK
schema:
$ref: '#/definitions/ArrayOfUsers'
401:
$ref: '#/responses/Unauthorized' # <-----
/users/{id}:
get:
summary: Gets a user by ID.
response:
200:
description: OK
schema:
$ref: '#/definitions/User'
401:
$ref: '#/responses/Unauthorized' # <-----
404:
$ref: '#/responses/NotFound' # <-----
# Descriptions of common responses
responses:
NotFound:
description: The specified resource was not found
schema:
$ref: '#/definitions/Error'
Unauthorized:
description: Unauthorized
schema:
$ref: '#/definitions/Error'
definitions:
# Schema for error response body
Error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
ルートレベルで定義されたレスポンスは、すべての操作に自動的に適用されるわけではないことに注意してください。これらは、複数の操作で参照および再利用できる単なる定義です。
FAQ
リクエストパラメータに基づいて異なるレスポンスを持つことはできますか？たとえば、次のように。
GET /something -> {200, schema_1}
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
お探しの情報が見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください