API Contract & Breaking Change Analyzer
Find breaking changes between two versions of an OpenAPI spec
- Runs in your browser
- OpenAPI 3.0 and 3.1
- Breaking and non-breaking changes
About API Contract & Breaking Change Analyzer
Paste the old and new versions of an OpenAPI 3.0 or 3.1 document to see which changes could break existing clients: removed endpoints, new required parameters, narrowed enums, stricter types, changed nullability and new security requirements. Local $ref references are resolved before comparing, and the report exports to Markdown or JSON for a pull request or your own CI checks.
What counts as a breaking change
A change is breaking when a client built against the old contract could fail against the new one. Removing an endpoint, adding a required request parameter, narrowing an enum, tightening a type or adding a security requirement all qualify. Adding an optional request field or a new response field usually doesn’t.
Direction matters. Making a request field required breaks clients that don’t send it; making a response field optional breaks clients that assumed it was always there. The analyzer applies separate rules to requests and responses.
Using it in review
Run the comparison when an OpenAPI file changes in a pull request. Paste the Markdown summary into the review, or keep the JSON report for your own CI checks. A breaking change isn’t always wrong, but it should be deliberate and versioned.
Limits
The analyzer compares what the specification says, not how the API behaves. Local $ref references are resolved; remote references aren’t fetched, so bundle external schemas into one file before comparing.
Further reading
Questions people ask
- Which OpenAPI versions are supported?
- OpenAPI 3.0 and 3.1, in JSON or YAML. Swagger 2.0 documents need converting first.
- Are the specs uploaded?
- No. Both documents are parsed and compared in your browser.
- Can it fail my build automatically?
- Not directly. The JSON export is designed so your own CI step can read it and decide whether to fail.