不正な HTTP レスポンスステータスコード

説明

OpenAPI のレスポンスキーには、有効な HTTP ステータスコードまたは default を使用します。情報レスポンスを表す 1xx も有効です。OpenAPI 3.0 では、大文字の 1XX から 5XX までの範囲表記も使用できます。OpenAPI 2.0 では、この範囲表記は定義されていません。

レスポンスキーは、クライアントや API ツールが各ステータスの意味を理解するために使われます。文書に記載するステータスコードと応答の説明は、実際の API の動作と一致している必要があります。

想定される影響

• API 文書が、実装から返される状態を正しく説明できない可能性があります。
• コード生成、文書化、テストの各ツールが不正なキーを拒否したり、異なる扱いをしたりするおそれがあります。
• 文書と実際の応答が異なると、クライアントのエラー処理やリダイレクト処理が意図どおりに動作しない可能性があります。

対処方法

実装が実際に返す応答に合ったコードを使用してください。一般的な例は 200、404、500 です。個別に定義していない応答は default で説明できます。範囲表記が必要なら OpenAPI 3.0 の大文字表記を使い、2.0 では個別のコードまたは default を使用してください。各コードの意味は HTTP ステータスコードの登録簿で確認してください。使用する OpenAPI バージョンに対応した検証ツールで文書全体を検証し、実際の API の応答とも比較してください。

レスポンスキーの例

以下の例は、レスポンスキーの形式と意味をそれぞれ確認するためのものです。必須の info オブジェクトなどを省略しており、完全な OpenAPI 文書ではありません。2 番目の例の 310 も、そのまま使用することは推奨しません。

不正なレスポンスキー

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "50": {
            "description": "Invalid status"
          },
          "6xx": {
            "description": "Invalid range"
          }
        }
      }
    }
  }
}

意味の確認が必要なステータスコード

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "OK"
          },
          "310": {
            "description": "Redirect"
          }
        }
      }
    }
  }
}

説明:

• 不正なレスポンスキー: 50 は 3 桁のステータスコードではなく、6xx は許可された HTTP ステータスコードの範囲ではありません。
• 意味の確認が必要なステータスコード: 200 はリクエストの成功を示しますが、310 は標準のリダイレクトコードとして登録されていません。実際の動作に合った 301 や 302 などを選ぶ必要があります。

参考資料

• OpenAPI 3.0.3 Responses Object
• OpenAPI 2.0 Responses Object
• IANA HTTP ステータスコード登録簿
• CWE-20