OpenAPI Diff
Compare two OpenAPI specs and see a breaking-changes report: removed endpoints, changed types, new required params, and more.
About this tool
OpenAPI Diff compares two versions of an OpenAPI specification — paste an old version and a new version (JSON or YAML), and it spotlights every breaking change: removed endpoints, deleted HTTP methods, parameter type changes, newly required parameters, dropped enum values, and missing response fields.
Example: comparing a v1 spec where GET /pets accepts an optional limit query parameter against a v2 where limit became required surfaces it as an error. If the v1 response included a species field that v2 dropped, that appears as a warning.
Use it before shipping an API change: paste the current spec and your draft, then review every flagged item. The report is color-coded by severity — errors need fixing, warnings deserve a second look, and info items document what's new so you can update your changelog.
FAQ
What counts as a breaking change? ›
The tool flags errors (removed endpoints, deleted HTTP methods, removed parameters, changed parameter types, optional→required param changes, missing enum values, changed response property types) and warnings (new required parameters, removed response properties). Items marked "info" are non-breaking additions.
Does it handle YAML specs? ›
Yes. Paste JSON or YAML — the tool auto-detects the format. It uses js-yaml for YAML parsing, so multi-line strings, anchors, and typical OpenAPI YAML patterns are supported.
Does it resolve <code>$ref</code> references? ›
Internal <code>#/components/...</code> refs are resolved against the new spec, so parameter and schema changes across reused components are tracked. External URL refs are not followed — inline all <code>$ref</code>s first if you need those checked.
How is this different from JSON Diff? ›
JSON Diff compares any two JSON objects structurally — it shows byte-level differences but does not understand OpenAPI semantics. This tool understands <code>paths</code>, <code>parameters</code>, <code>responses</code>, <code>schemas</code>, and <code>enums</code>, so it tells you which endpoints broke and why. For structural comparison of arbitrary JSON, use <a href="/json-diff" class="text-accent hover:underline">JSON Diff</a>.