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

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

- URL: https://tools.itlibra.com/ja/openapi-diff
- 端末内で処理・アップロードなし
- 最終更新: 2026-10-26

## 使い方

1. 左に変更前、右に変更後の定義を貼り付けるか、「ファイルを開く」で読み込みます（YAML・JSON、OpenAPI 3.0・3.1、Swagger 2.0）。「サンプルで試す」でも確かめられます。
2. 「差分を調べる」を押す（Ctrl または ⌘ + Enter も使えます）と、破壊的・注意・非破壊の件数と判定が出ます。判定は 1 行で、破壊的な変更があれば終了コード 1 相当です。
3. 一覧は区分で絞り込めます。各行には、パス・メソッド・場所・内容と、その区分になった理由が出ます。判定の規則は一覧の下の表で読めます。
4. 「Markdown をコピー」で PR の説明に貼れる表にできます。「JSON を保存」では、判定・件数・変更の一覧を機械的に読める形で保存します。

## こんなときに

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

## できること

### 破壊的な変更を区分

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

### 判定の理由を各行に

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

### $ref を解決して比べる

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

### Markdown と JSON で書き出し

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

### ブラウザの中だけで処理

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


## 対応形式

### 入力

- OpenAPI 3.0.x
- OpenAPI 3.1.x
- Swagger 2.0
- .yaml / .yml / .json
- UTF-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 行目に「破壊的な変更があります」か「ありません」で示されます。