OpenAPI 3.0 または 3.1 の JSON/YAML をチェックして、一般的な構造エラー、レスポンスの欠落、未解決のローカル参照、パスパラメータの欠落を検出します。
ブラウザ内でローカルに実行OpenAPI 3.0 または 3.1 の JSON/YAML を貼り付けてください。定義はこのブラウザ内に留まり、外部から取得されたりアップロードされたりすることはありません。
info、パス、オペレーション、レスポンスオブジェクト。#/... 参照とパスパラメータ宣言の欠落。これは作成支援に特化したリンターであり、完全なスキーマ適合性テストスイートや稼働中 API の契約テストの代わりにはなりません。
各所見には重要度と対象要素の JSON Pointer が付くため、問題が定義のどの位置にあるかをたどれます。
openapi のバージョン文字列、info オブジェクト、paths オブジェクトの欠落はエラーで、info の中では title と version が必須です。/ で始まらないパスキーもエラーで、responses オブジェクトが空の操作も同じです。利用側には少なくとも 1 つのステータスコードか default が必要だからです。
/orders/{id} のようなパステンプレートは、{id} を in: path と required: true 付きで宣言する必要があります。これがないと呼び出しを組み立てられないためです。#/components/... 形式の参照は解決し、どこにもつながらない参照はその位置のポインターでエラーとして報告します。
operationId のない操作は警告です。生成されたクライアントがメソッド名に使うためです。content マップのない requestBody、別ファイルや URL を指す参照、swagger: "2.0" の文書も警告になります。servers 配列がない定義は注意で、利用側は OpenAPI の既定 URL を使います。
バージョン文字列が存在していても 3.x でない場合、たとえば "3" や "4.0.0" はエラーではなく警告になります。そのため、あと少しで正しくなる定義でもレポート全体は出力されます。
pointer 内の ~1 はパス中のスラッシュを表すため、/paths/~1orders~1{id}/get は GET /orders/{id} です。1 回の実行で見つかった所見はまとめて並ぶので、複数の問題がある文書でも何度も検証し直す必要はありません。
webhooks と components.pathItems は OpenAPI 3.1 で認められており、操作として数えません。paths オブジェクトが空でも有効で、そのまま通ります。
検査するのは構造とローカル参照だけです。セキュリティスキーム、タグの慣習、命名スタイル、API 設計が妥当かどうかは対象外で、稼働中のサーバーへの問い合わせも行いません。同じ operationId を持つ 2 つの操作は報告しません。
サンプルデータの中、つまり example の中身、examples の各項目の value、enum、const では、$ref というキーは参照ではなくデータとして扱います。そのため、たまたま $ref を含むペイロードが誤ったエラーになることはありません。