OpenAPI 差分・破壊的変更チェッカー

OpenAPI Diff は、ベースラインと候補の API 仕様をテキストではなく意味で比較します。オペレーションをメソッドとパスで対応付け（/users/{id} と /users/{userId} は同じエンドポイントとして扱います）、内部の $ref 参照を解決し、契約上の各変更を、そのオペレーション、場所、変更前後の値、クライアントにとっての影響とともに報告します。JSON または YAML の Swagger 2.0、OpenAPI 3.0、OpenAPI 3.1 に対応しており、Swagger 2.0 は最初に OpenAPI 3 の形に正規化されます。

1. 1.ベースライン仕様（クライアントが現在使っているバージョン）を貼り付け、アップロード、またはインポートします。
2. 2.候補仕様（提案するバージョン）を追加します。
3. 3.「比較」を選択します。
4. 4.「破壊的変更」「警告」「互換性あり」の各タブを確認し、メソッドや領域で絞り込みます。
5. 5.変更を選択すると、変更前後の値とその影響の理由が表示されます。
6. 6.プルリクエスト用に破壊的変更をコピーするか、CI 用に Markdown または JSON のレポートをダウンロードします。

リクエストとレスポンスは、逆の方向で判定されます。リクエスト側（クライアントが送信するもの）では、受け付ける範囲を狭めるものはすべて破壊的変更です。具体的には、必須パラメーターやプロパティの追加、enum 値の削除、型や形式の変更、最大値の引き下げや最小値の引き上げ、新しいパターン、コンテンツタイプの削除などです。レスポンス側（クライアントが受け取るもの）では、クライアントが読み取る内容を削除したり広げたりするものは、破壊的変更または警告になります。具体的には、プロパティや成功ステータスの削除、型の変更、新しい enum 値、必須プロパティが任意になったことなどです。エンドポイントの削除、新たな認証、セキュリティスキームの変更、OAuth スコープの追加は破壊的変更です。説明、概要、タイトル、例の編集はドキュメントの変更として扱われ、オンにしない限り表示されません。

比較はブラウザー内で組み込みのルールエンジンにより実行され、仕様がアップロードされることはありません。URL のインポートでは、Cookie なしでブラウザーから直接ファイルを取得するため、クロスオリジンリクエストをブロックするサーバーの仕様はアップロードまたは貼り付けが必要です。各仕様のサイズは最大 5 MB です。外部の $ref ファイルは報告されますが、取得はされません。サーバー、コールバック、Webhook、リンク、ベンダー拡張は比較されません。また、ルールが示すのはクライアントへの影響の見込みであり、保証ではありません。厳格なサーバーと寛容なサーバーでは動作が異なる場合があります。