説明
responses の default は、個別に定義していないステータスコードのレスポンスを説明します。省略可能でエラー専用でもありませんが、未記載のレスポンスが共通の形式を使う場合に役立ちます。
想定される影響
実際に返すエラーレスポンスの形式が文書にないと、クライアントや生成されたSDKが正しく処理できない可能性があります。
対処方法
既知の成功レスポンスとエラーレスポンスを文書化し、残りのレスポンスに共通の契約が必要な場合は default を追加してください。その意味と、実際に返す本文の形式を説明してください。
例
次のOpenAPI 3.0の抜粋では、本文のない 204 の成功レスポンスに加え、個別に定義していないエラーレスポンスの説明を default で追加しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"responses": {
"204": {
"description": "Item updated successfully"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"responses": {
"204": {
"description": "Item updated successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}