OpenAPI Diff

この比較ツールがチェックすること——そして「破壊的」の本当の意味

変更が破壊的であるのは、旧仕様に対して正しく書かれたクライアントが、自分のコードを1行も変えずに新仕様で失敗しうるときです。このページのすべての判定はこの定義に基づきます。パスや操作の削除は破壊的です。既存の呼び出しの行き先がなくなるからです。レスポンスステータス——とりわけ2xx——の削除は破壊的です。クライアントのエラー処理は旧ステータスの集合を前提に書かれているからです。必須パラメータや必須のリクエストプロパティの追加は破壊的です。昨日まで有効だったリクエストが突然拒否されるからです。フィールドの型やフォーマットの変更は破壊的です。パーサ、バリデータ、生成されるSDKはすべて宣言された型を前提にしているからです。列挙値の削除は破壊的です。クライアントは今もその値を送るかもしれず、解釈できなくなったデータを保持しているかもしれないからです。それ以外——新しいエンドポイント、任意パラメータ、新しいレスポンスフィールド、新しい列挙値、新しいステータスコード——はすべて非破壊的として報告されます。古いクライアントは動き続けます。新しい機能をまだ使えなくてもです。

比較はテキストではなく構造で行われます。両ドキュメントは比較の前に同じモデルへ正規化されます。各パスと操作、その名前と場所で索引付けされたパラメータ、リクエストボディと各レスポンスは、スキーマシグネチャへと還元されます。これは型、フォーマット、プロパティ名、必須リスト、列挙値から再帰的に構築される決定的な要約で、ローカルの $ref 参照は解決されます。だからこそ、キーの順序を変えたり、空白を整形し直したり、すべての説明文を書き換えたりしても、差分は空になります。それらは契約を変えないからです。そして、参照されるスキーマの3階層深くに埋もれた変更も見つかります。シグネチャは参照の名前を比較するのではなく、参照を展開するからです。

エコシステムが両方を公開しているため、入力形式は2種類を受け付けます。まずJSONとして試し、失敗した場合はYAMLとして解析します。手書きのOpenAPIドキュメントの多くがYAMLを使っています。Swagger 2.0のドキュメントも動作します。in: body パラメータやレスポンスごとのスキーマも含みます。意図的に、ライブ取得もアップロードもありません。HARキャプチャと同じようにドキュメントを貼り付けるかファイルをドロップしてください。比較はキーを押すたびではなく、ボタンを押したときに実行されるため、貼り付けた2つの大きな仕様でも応答性が保たれます。

結果は飾りではなく、リリースのゲートとして使ってください。レビューでは、破壊的リストが議題そのものです。各エントリには、修正、バージョン番号の引き上げ、非推奨期間の設定、あるいは「破壊は意図的で周知済み」という書面の決定のいずれかが必要です。非破壊的リストは変更履歴の下書きです。差分をJSONでエクスポートすれば、その決定をリリースの横に保管でき、コピーできる要約はプルリクエストにそのまま入ります。これは、ペイロードが静かに変更されるとすべての購読者が同時に壊れる webhook の契約変更に適用するのと同じ規律です。

正直な限界を明言します。この比較ツールは宣言された契約を比較します。仕様が宣言していない振る舞いは見えません。型は同じでも意味が変わったフィールド、新しい業務ルール、より厳しいレート制限、クライアントが（賢明とは言えず）解析していたエラーメッセージなどです。ローカル参照をたどり、有限の深さまでスキーマを比較するため、病的に深く入れ子になったスキーマや相互再帰スキーマは、無限に展開されるのではなく要約されます。そして、破壊的変更ゼロの差分は、アップグレードが安全だという約束ではありません。文書化された契約が保たれたという証拠であり、それこそがデプロイ前に持つ価値のある証拠なのです。