明示・範囲・default・未定義が混ざる
ペット API の仕様に対して、7 件の観測を突き合わせる代表例です。範囲の 4XX、default、5XX による定義と、POST の 500 だけが未定義になることを確かめます。
入力
OpenAPI 文書(JSON)
{"openapi":"3.1.0","paths":{"/pets":{"get":{"responses":{"200":{},"4XX":{},"default":{}}},"post":{"responses":{"201":{},"400":{}}}},"/pets/{id}":{"get":{"responses":{"200":{},"404":{},"5XX":{}}}}}}観測した応答(1 行に「メソッド パス コード」)
GET /pets 200 GET /pets 404 GET /pets 500 POST /pets 201 POST /pets 500 GET /pets/7 404 GET /pets/7 503
結果
エラー 0 件・警告 1 件・情報 1 件
指摘(エラー・警告・情報)
- 情報 3 行目 GET /pets のコード 500 は個別に宣言されておらず、default の定義で受けています。個別に宣言するかは仕様の書き方の判断です。
- 警告 5 行目 POST /pets にコード 500 の定義がありません(500・5XX・default のいずれもない)。応答の定義を追加するか、観測が想定外でないか確認してください。
| 観測した応答 | 7 件 |
|---|---|
| 定義あり | 5 件 |
| default で受けるもの | 1 件 |
| 未定義 | 1 件 |
判定の一覧
| 行 | 操作 | コード | 判定 |
|---|---|---|---|
| 1 | GET /pets | 200 | 定義あり(明示のコード) |
| 2 | GET /pets | 404 | 定義あり(範囲 4XX) |
| 3 | GET /pets | 500 | 個別の定義なし(default で受ける) |
| 4 | POST /pets | 201 | 定義あり(明示のコード) |
| 5 | POST /pets | 500 | 未定義 |
| 6 | GET /pets/{id} | 404 | 定義あり(明示のコード) |
| 7 | GET /pets/{id} | 503 | 定義あり(範囲 5XX) |
検算(この結果になる理由)
GET /pets は 200 が明示、404 は 4XX の範囲、500 は default が受けます。POST /pets は 500 の明示も 5XX も default もないので未定義です。/pets/7 はテンプレート /pets/{id} に当たり、404 は明示、503 は 5XX の範囲です。
判定の根拠は仕様と根拠に、仕様の出典とともにまとめています。自分の入力で試すにはツールをお使いください。
このツールの制約
- JSON 形式の文書だけを読みます。YAML は未対応で、先に JSON に変換してください。
- $ref で別の場所を参照する応答の中身は見ません。コードのキーが定義されているかだけを判定します。
- 応答の本文やヘッダーが仕様に合っているかは検査しません。ステータスコードの有無だけです。
- paths の外(webhooks など)や、パスのテンプレートが複数の区間にまたがる指定には対応していません。
ご利用にあたって
- 運用で観測した応答が仕様にないとき、仕様が古いのか実装が想定外なのかは、このツールでは判断できません。開発の担当者と確認してください。