01
旧版と新版の向きを確認
既存クライアントを基準に判定します。入れ替えはプレビュー後に適用され、直前の入力と報告を一度だけ復元できます。
API契約ツール
OpenAPI仕様の差分公開前に影響を確認
旧版と新版を別々に貼り付け、方向を確かめてから比較します。
OpenAPI仕様の差分
旧版の仕様
新版の仕様
変更レポート
二つの仕様はこのブラウザー内で処理され、API要求は送信されません。
比較オプション
対象は要求操作、パラメーター、要求本文、応答です。実際の互換性は証明しません。
二つの仕様を貼り付けて比較してください。
OpenAPI仕様の差分を見る場面は、既存クライアントが使う契約を更新するときです。行単位の差分だけでは、削除された操作と新たな必須パラメーターの影響を読み取りにくくなります。
このページはOpenAPI仕様の比較を操作と応答の単位で示します。API契約の差分のうち判断材料が足りないものは「要確認」に残し、安全とは断定しません。
OpenAPI仕様の差分を使う理由
旧版利用者への影響を先に見る
OpenAPI仕様の差分は旧契約から新契約への変更として判定します。応答フィールドの削除と経路の追加を分けるので、破壊的な可能性を先に確認できます。
除外した経路も記録に残す
完全一致のパスだけを両仕様から除外し、報告には除外したパスを残します。ワイルドカードの解釈を推測せずに比較範囲を共有できます。
比較前に決める三つのこと
02
除外するパスを正確に書く
/internal/healthのようなOpenAPIの完全なパスを一行ずつ入力します。正規表現でもJSON Pointerでもありません。変更後は再比較が必要です。
03
分類の意味を読んでから出力
OpenAPI破壊的変更は潜在的な失敗、要確認は追加調査が必要な変更です。画面の絞り込みは、全件を含むJSONとMarkdownの出力を変えません。
操作と応答に残る変更の証拠
経路とHTTPメソッド
旧版の操作が削除された場合は破壊的な可能性として表示し、新規操作は別に示します。単なるテキスト差分より対象が明確です。
入力と応答
必須パラメーター、必須の要求フィールド、削除された応答やフィールドを追います。解決できる単純な型とenumの変更も表示します。
受け渡せる報告
各変更にメソッド、パス、判定規則、前後の値を残します。最新の完全な結果だけをJSONまたはMarkdownで書き出せます。
静的な契約比較で扱わないもの
- URLから取得しない
- 貼り付けたJSONまたはYAMLだけを使います。外部の仕様URLや実際のAPIへ要求を送信しません。
- 除外は完全一致のみ
- パスのワイルドカード、正規表現、callback経路は扱いません。パス名が異なれば別の操作として示します。
- 参照が不完全なら中断
- 外部$ref、未対応の方言、webhookやcallbackがあると完全なリスク報告を出しません。未解析部分を安全とは呼べないためです。
- 実際の動作は証明しない
- 仕様の変化だけではサーバーの挙動もSDKの互換性も確定しません。既存クライアントのテストと併用してください。
OpenAPI仕様の差分についてよくある質問
OpenAPI仕様における破壊的変更を検出するにはどうすればよいですか？
旧版と新版を貼り付けて比較します。削除された操作、新たな必須入力、失われた応答フィールドを潜在的な破壊的変更として表示し、規則と前後の値を確認できます。
APIの「後方互換性」とは何を意味しますか？
旧契約に従った呼び出しが新契約で失敗しないか、という意味です。OpenAPI仕様の差分は静的な候補を示しますが、稼働中のAPIの互換性を保証しません。
実際のAPIで最もよくある破壊的変更は何ですか？
操作やメソッドの削除、必須パラメーターの追加、応答フィールドの削除が代表例です。認証や複雑なSchemaは要確認として扱います。
既存クライアントを壊さずにenum値を追加するにはどうすれば良いですか？
応答側のenum値追加は厳格なクライアントで問題になる可能性があるため要確認です。既存の利用者と生成済みSDKをテストして判断してください。
偶発的な破壊的変更を防ぐテストはどう組むべきですか？
このページはCI門番ではありません。JSONまたはMarkdown報告を保存し、契約テストとクライアントテストをリリース手順に組み合わせてください。 自動チェックが必要ならoasdiffなどを別途検討してください。
比較は役に立ちましたか？