説明
OpenAPI操作のresponsesには、実際の正常な結果と既知のエラーを記述します。正常な結果が欠けると、利用者が応答を予測しにくくなります。2xxの定義がないだけで文書が不正になるわけではなく、リダイレクトなど意図した動作も確認する必要があります。
想定される影響
クライアントやテストが正常応答をエラーと扱ったり、必要なレスポンス本文を処理できなかったりする場合があります。
対処方法
実際の動作に合う状態コード、説明、必要なヘッダーや本文を定義してください。慣例だけで200、201、204などを追加しないでください。OpenAPI 3.0の2XX範囲応答やdefaultの対象も確認し、仕様バージョンが許可する形式を使ってください。
例
応答部分だけを示すOpenAPI 3.0の抜粋で、infoは省略しています。300は有効なHTTP状態コードなので、意図した結果かを確認してください。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"300": {
"description": "Redirect"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
変更後は、操作が実際に通常の成功応答を返すと仮定して200を定義しています。サーバーがリダイレクトを返すのに文書だけを200にすると、契約の記述が誤るため実際の応答に合わせてください。