日本語English

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

変更前と変更後の OpenAPI（または Swagger 2.0）を貼るだけで、クライアントが壊れる破壊的な変更を一覧します。パスの削除・必須項目の追加・型の変更などを「破壊的」「注意」「非破壊」に分け、各行に判定の理由を付けます。定義はブラウザの外へ送りません。

端末内で処理・アップロードなしスマホ対応オフライン対応

ファイルや入力内容はお使いの端末（ブラウザ）の中だけで処理され、サーバーへは送信されません。

変更前（古い定義）
0 / 2,000,000
変更後（新しい定義）
0 / 2,000,000
1 つの定義は 200 万文字・3,000 操作まで。Ctrl（⌘）+ Enter で実行します。
「差分を調べる」で結果が表示されます。
判定の規則
  • 破壊的 クライアントが壊れやすい変更
  • 注意 実装や呼び出し方によって影響が変わる変更
  • 非破壊 既存のクライアントはそのまま動く変更
区分判定の理由
破壊的パスが削除された。このパスを呼ぶクライアントは 404 などで失敗します。
破壊的操作（メソッド）が削除された。その操作を呼ぶクライアントが失敗します。
非破壊操作を追加した。既存の呼び出しには影響しません。
破壊的認証・認可が新しく必要になった。認証情報を送らないクライアントは拒否されます。
注意認証が不要になった。挙動は広がりますが、意図したものかを確認してください。
破壊的成功（2xx）の応答コードが消えた。その応答を前提にしたクライアントの処理が変わります。
注意成功以外の応答コードが消えた。エラー処理が不要になるか、想定しないコードが来る可能性があります。
非破壊応答コードを追加した。既存の処理は変わりません。
破壊的リクエストで使えた Content-Type（形式）が消えた。その形式で送るクライアントが失敗します。
非破壊リクエストで使える Content-Type（形式）を追加した。
破壊的レスポンスの Content-Type（形式）が消えた。その形式を前提にするクライアントが壊れます。
非破壊レスポンスの Content-Type（形式）を追加した。既存のクライアントは変わりません。
破壊的必須のリクエストボディを追加した。今まで送っていなかったクライアントが失敗します。
非破壊任意のリクエストボディを追加した。
注意リクエストボディを削除した。送っていた値が無視されるか拒否されるかは実装次第です。
破壊的リクエストボディが任意から必須になった。省いていたクライアントが失敗します。
非破壊リクエストボディが必須から任意になった。
破壊的必須のパラメーターを追加した。今まで送っていなかったクライアントが失敗します。
非破壊任意のパラメーターを追加した。
注意パラメーターを削除した。送られても無視されるかどうかは実装次第です。
破壊的任意のパラメーターが必須になった。省いていたクライアントが失敗します。
非破壊必須のパラメーターが任意になった。
破壊的同じ名前のパラメーターの指定場所（in）が変わった。送る場所が違うためクライアントが失敗します。
破壊的パラメーターの型または形式が変わった。今の値が受け付けられなくなる可能性があります。
破壊的パラメーターで受け付ける値が減った。その値を送るクライアントが失敗します。
非破壊パラメーターで受け付ける値が増えた。
破壊的リクエストに必須のプロパティを追加した。今まで送っていなかったクライアントが失敗します。
非破壊プロパティを追加した。リクエストでは任意、レスポンスではクライアントが読まなければ無視できます。
注意リクエストのプロパティを削除した。送られても無視されるかは実装次第です（additionalProperties: false なら拒否されます）。
破壊的レスポンスのプロパティが消えた。それを読むクライアントが壊れます。
破壊的リクエストのプロパティが任意から必須になった。省いていたクライアントが失敗します。
非破壊リクエストのプロパティが必須から任意になった。
非破壊レスポンスのプロパティが必ず含まれるようになった。
注意レスポンスのプロパティが必須から任意になった。省かれる前提のないクライアントは注意してください。
破壊的型が変わった（例: string から integer へ）。値の解釈が合わず、クライアントが壊れます。
注意形式（format）が変わった。解釈が変わる可能性があるため確認が必要です。
破壊的リクエストで受け付ける値が減った。その値を送るクライアントが失敗します。
非破壊リクエストで受け付ける値が増えた。
非破壊レスポンスの値の候補が減った。受け取る側の分岐が不要になるだけです。
注意レスポンスに新しい値が増えた。クライアントが知らない値を受け取る可能性があります。
注意oneOf・anyOf の候補が増減した。候補ごとの判定はしていないので、内容を確認してください。
注意読み込んでいないファイルや URL を指す $ref のため、この箇所は比べていません。変わっていても検出されないので、内容を確認してください。
判定は一般的な互換性の考え方によるもので、API ごとの方針で変わります。

使い方

  1. 左に変更前、右に変更後の定義を貼り付けるか、「ファイルを開く」で読み込みます（YAML・JSON、OpenAPI 3.0・3.1、Swagger 2.0）。「サンプルで試す」でも確かめられます。

  2. 「差分を調べる」を押す（Ctrl または ⌘ + Enter も使えます）と、破壊的・注意・非破壊の件数と判定が出ます。判定は 1 行で、破壊的な変更があれば終了コード 1 相当です。

  3. 一覧は区分で絞り込めます。各行には、パス・メソッド・場所・内容と、その区分になった理由が出ます。判定の規則は一覧の下の表で読めます。

  4. 「Markdown をコピー」で PR の説明に貼れる表にできます。「JSON を保存」では、判定・件数・変更の一覧を機械的に読める形で保存します。

できること

破壊的な変更を区分

パスや操作の削除、必須項目の追加、型の変更、レスポンスのプロパティの削除などを「破壊的」にまとめます。注意と非破壊の変更は別の区分にします。

判定の理由を各行に

どの規則でその区分になったかを、行ごとに日本語で示します。規則の一覧も画面で読めるので、判定の根拠をそのままレビューに使えます。

$ref を解決して比べる

同じ定義の中の $ref（#/components/... や #/definitions/...）をたどり、スキーマの中身まで比べます。循環する定義でも止まります。

Markdown と JSON で書き出し

PR に貼れる Markdown の表と、機械的に読める JSON を書き出せます。判定は終了コード相当の 1 行でも示します。

ブラウザの中だけで処理

定義は Web Worker の中で、ブラウザの外へ出さずに比べます。通信も外部の $ref の取得もしません。

こんなときに

  • API の改版で、既存のクライアントを壊す変更がないかを PR を出す前に確かめたい
  • 必須項目の追加やパスの削除を、レビューの前に機械的に洗い出したい
  • 社内 API の定義を外部に送らずに、変更前後の差を調べたい
  • 「破壊的変更があるか」の判定だけを 1 行で確かめたい

対応形式

入力

OpenAPI 3.0.xOpenAPI 3.1.xSwagger 2.0.yaml / .yml / .jsonUTF-8（BOM 付き可）

出力

画面の一覧（区分で絞り込み）Markdown（PR 用の表）JSON（判定・件数・変更の一覧）

対応状況

機能対応補足
OpenAPI 3.0・3.1・Swagger 2.0 の 2 つの定義の比較対応—
パス・操作の追加と削除対応—
パラメーターの必須化・削除・指定場所（in）・型・形式・enum の変更対応—
リクエストボディとレスポンスのスキーマ（プロパティ・型・必須・enum）対応入れ子は深さ 12 まで。超えた部分は比べず、確認メモに書きます
同じ定義の中の $ref の解決（#/components/... や #/definitions/...）対応—
別ファイルや URL にある $ref の取得非対応通信しないため取得せず、「解決できない $ref」として示します
利用状況を踏まえた影響範囲の判定（どのクライアントが壊れるか）非対応実際の利用は分からないため、一般的な互換性の考え方で判定します
API ごとの方針に合わせた判定の変更非対応規則は画面で読めますが、区分を変える設定はありません
Swagger 2.0 と OpenAPI 3.x の混在比較一部対応対応する項目だけを比べます。対応が取れない変更は判定に入らないことがあります
oneOf・anyOf の候補ごとの判定一部対応候補の増減だけを注意として示します
API を実際に呼び出しての動作確認非対応—
オフラインでの利用対応一度開いたあとは通信なしで動作します

制限・注意事項

  • 1 つの定義は 200 万文字・3,000 操作まで。ファイルは 5 MB まで読み込みます。
  • 一覧と書き出しは 1,000 件まで。件数は全件を数えます。
  • 入れ子のスキーマは深さ 12 まで、スキーマの比較は 2 万回まで。超えた部分は比べず、確認メモに書きます。
  • 2.0 と 3.x を比べると、対応する項目が見つからない場合があります。
  • 判定は一般的な互換性の考え方によるもので、API ごとの方針によって変わります。

プライバシーと安全性

定義はお使いのブラウザの中だけで比べられ、送信も保存もしません。外部の $ref は取得しません。ページを閉じると内容は消えます。analytics には、入力の中身や件数を含まない実行の記録だけを送ります。

よくある質問

OpenAPI の破壊的変更とは何ですか？
既存のクライアントが今までどおり動かなくなる変更のことです。パスの削除、必須のリクエスト項目の追加、型の変更などが該当します。このツールは一般的な互換性の考え方で判定します。
破壊的かどうかの判定は正確ですか？
一般的な互換性の考え方による判定です。API ごとの方針や、実際にどのクライアントが使っているかは分かりません。判定の規則は画面で読めるので、最終的な判断はレビューで行ってください。
Swagger 2.0 と OpenAPI 3.0 を比べられますか？
比べられます。ただし 2.0 と 3.x では書き方が違うため、対応する項目だけを比べます。同じバージョン同士で比べるほうが確実です。
別ファイルの $ref も比べられますか？
いいえ。このツールは 1 つの定義の中の $ref だけを解決します。別ファイルや URL の参照は取得せず、「解決できない $ref」として表示します。
比較結果を PR に貼るには？
「Markdown をコピー」で、判定・件数・変更の表をコピーできます。判定は 1 行目に「破壊的な変更があります」か「ありません」で示されます。

OpenAPI ビューア・検証（OpenAPI Studio）

OpenAPI 3.0 / 3.1・Swagger 2.0 の定義を貼り付けるだけで、タグ別のエンドポイント一覧とスキーマのツリーを表示し、公式スキーマと照らして誤りを行・列つきで示します。API の呼び出しや外部ファイルの取得はせず、定義は端末の外へ送信しません。

アップロードなし

テキスト・コード Diff

変更前と変更後を貼り付けるかファイルをドロップするだけで、追加・削除された行と、行の中で変わった単語まで色分けして表示します。結果は unified 形式のパッチとしてコピー・保存でき、入力はブラウザの外へ出ません。

アップロードなし

JSON 整形・検証（JSON Studio）

JSON を貼り付けるだけで整形・1 行化・構文チェック。エラーは「何行目の何が悪いか」まで表示し、コメントや末尾カンマは自動修復できます。データは端末の外へ送信しません。

アップロードなし

UUID / ULID / NanoID / トークン生成

ページを開いた瞬間に UUID が 1 件生成済み。種類を選ぶだけで UUID v7・ULID・NanoID・ランダムトークンに切り替わり、最大 1 万件を .txt / .csv / .json で保存できます。既存の UUID や ULID を貼り付ければ、埋め込まれた時刻やバージョンも読み取れます。

アップロードなし

正規表現テスター（Regex Tester）

パターンを入力すると、一致した箇所がテスト文字列の上で即座に色付けされます。キャプチャグループ・置換結果・パターンの意味まで一画面で確認でき、ブラウザを固まらせる危険なパターンは 1 秒で自動停止します。

アップロードなし

コード整形・圧縮（Code Formatter）

コードを貼り付けるだけで、言語を自動判定して整形できます。インデント・1 行の幅・セミコロン・引用符・末尾カンマを選べ、JavaScript・CSS・HTML は圧縮前後のサイズと削減率も表示。入力は端末の外へ出ません。

アップロードなし

最終更新: