OpenAPI互換性チェッカー
変更前後のOpenAPI 3.0.x定義（JSONまたはYAML）を比較し、パス・HTTPメソッドの削除、リクエスト項目の必須化、型の変更など、既存のAPI利用者に影響する変更を検出するツールです。変更箇所・変更前後・影響する理由をエンドポイントごとに表示し、外部参照など判定できない箇所は未判定として示します。すべてブラウザ内で処理されます。
- 対象は OpenAPI 3.0.x の定義（JSONまたはYAML）です。3.1 や Swagger 2.0 は判定しません。
- 検出する変更: パス・HTTPメソッドの削除、パラメーター・リクエストボディ・リクエストのプロパティの必須化、型の変更、nullable の変更。パスパラメーター名だけの変更（/users/{id} → /users/{userId}）は同じエンドポイントとして扱います。
- 同じ文書内の $ref は解決します。外部ファイル・URLへの参照、allOf・oneOf・anyOf・not を含むスキーマは「未判定」として表示します。enum・format・レスポンスのプロパティ削除なども検査していないため、検出なしは完全な互換性を保証するものではありません。
互換性チェックの結果
変更前と変更後のOpenAPI定義を入力すると、既存クライアントに影響する変更が表示されます。
使い方
- 左に変更前、右に変更後のOpenAPI定義（JSONまたはYAML）を貼り付けるか、ファイルを読み込みます。
- 互換性に影響する変更が、メソッドとパスごとにまとめて表示されます。
- 各変更の場所（パラメーター・リクエストボディ・レスポンスとプロパティのパス）と、影響する理由を確認します。
- 「未判定」は外部参照や合成スキーマなど、このツールでは判定できない箇所です。必要に応じて手動で確認してください。
このツールについて
APIを更新するとき、任意だったリクエスト項目を必須にしたり、レスポンスの型を変えたりすると、旧バージョンのクライアントがエラーになることがあります。このツールはOpenAPIの意味に基づいて定義を比較し、公開前にこうした変更を見つけます。
キーの順序や整形、JSONとYAMLの違いは問題として扱いません。パスパラメーターの名前だけを変えた場合（/users/{id} → /users/{userId}）は同じエンドポイントとして比較します。リクエストでは integer から number への変更のように受け付ける値が広がる変更、レスポンスではその逆を互換として扱います。
検査は限定的で、enum・format・レスポンスのプロパティ削除・セキュリティ定義などは対象外です。検出がなくても完全な互換性を保証するものではありません。入力した定義がサーバーへ送信されることはありません。
変更前に {"openapi":"3.0.3","paths":{"/ping":{"get":{"responses":{"200":{"description":"ok"}}}}}}、変更後に {"openapi":"3.0.3","paths":{}} を入れると、/pingの削除が破壊的変更として検出されます。
比較の向きは既存クライアントが変更後のAPIを使えるか、という基準です。左右を逆にすると削除が追加になり、結果も変わります。リリース前の定義を左、新しい定義を右に置き、未判定の参照先も含めて変更内容を確認してください。
よくある質問
OpenAPI 3.1 や Swagger 2.0 に対応していますか？
初期版は OpenAPI 3.0.x のみに対応しています。それ以外のバージョンは対応外として表示し、判定しません。
$ref は解決されますか？
#/components/schemas/User のような同じ文書内の参照は解決します。外部ファイルやURLへの参照は取得せず、未判定として表示します。
新しいエンドポイントの追加は表示されますか？
追加は既存クライアントに影響しないため表示しません。差分全体を確認したい場合は JSON構造比較ツールを使ってください。