WHAT IT DOES
Review API changes without mistaking a diff for a compatibility guarantee.
Compare OpenAPI 3.0.x or 3.1.x documents in JSON or the supported YAML subset. Removed paths and operations and selected required-input changes are marked potentially breaking. Other structural differences remain visible for review, including schema, security, and component changes. Nothing calls your API or fetches a reference.
Why use it?
An API can keep the same endpoint yet break callers by requiring a new input. Comparing contracts highlights those changes before an implementation or client rollout.
How to use this tool
- Place the original and updated OpenAPI 3.0.x or 3.1.x documents in the corresponding panes, or load an example.
- Compare and review each changed location, old and new value, and compatibility note.
- Check references, schema meaning, and runtime behavior separately. A structural diff is a review aid, not a complete backward-compatibility verdict.
Details and limitations
- Each document is limited to 10 MiB. JSON object key order is ignored; array ordering remains significant.
- YAML anchors, aliases, tags, directives, and multiple documents are not accepted; export a single JSON document for unsupported syntax.
- Displays the first 100 differences and includes up to 1000 in Copy report. Truncation is explicitly reported as an incomplete comparison.
- References are compared as written, not dereferenced. Full schema compatibility, callbacks, webhooks, and security semantics need manual review.
- An unchanged structural comparison is not a pass from an OpenAPI validator and does not prove existing clients will still work.
Review an OpenAPI change from the caller's point of view
Start with a request that used to work
Load the worked example on the OpenAPI Change Inspector page and compare the documents. Both describe GET /items, but the updated contract adds a required query parameter named tenant. The earlier caller could request /items without that parameter. The difference is relevant even though no operation was removed. The tool marks this as potentially breaking rather than claiming to know whether the deployed server already accepts the old call.
Before: GET /items
After: GET /items?tenant=demo
Expected review: a required query parameter was added.Read the path and the reason together
The report identifies the affected document location and old and new values. A newly required input deserves a caller migration plan; an added operation does not cancel another incompatible change. Array ordering remains significant in this tool, so reordered parameters can create differences that need identity-based review. Read the parameter name and location rather than treating every changed array index as a separate API decision.
Account for what is not expanded
The inspector accepts OpenAPI 3.0.x and 3.1.x and compares references as written. It never fetches a remote $ref. If the reference string stays the same while its external file changes, this comparison cannot see that change. Bundle the referenced definitions before comparing if their contents are part of your review. Unsupported YAML constructs need a single JSON export. If the report says it is truncated, you do not have a complete comparison.
Test behavior outside the document
Use the request builder or cURL converter to prepare representative old and new requests, then run them only against a test service you control. These tools prepare text; they do not call the API for you. Check old-client behavior, response shapes, authorization, and error cases. An unchanged document can coexist with a changed implementation, and a clean structural comparison is not schema validation or evidence that your clients are safe to deploy.