Venture Lab How to detect breaking changes between two OpenAPI specs
A change is breaking when a client that worked yesterday fails today without changing its code. Comparing the old and new spec before release catches most of these.
Changes that break existing clients
| Change | Why it breaks |
|---|---|
| An operation (path + method) is removed | Clients that call it get an error |
| A new required parameter | Existing calls do not send it |
A parameter's type changes, for example integer → string | Existing values may no longer validate |
| The request body becomes required | Calls without a body are now invalid |
| A documented response is removed | Clients that handle that status lose their contract |
| A parameter is removed | Clients that send it may have it ignored or rejected |
New operations, new optional parameters and new responses are usually safe.
Marking an operation as deprecated breaks nothing by itself. It is a signal to plan the migration.
What the spec says about parameters
The OpenAPI Specification defines a unique parameter by the combination of its name and location (in).
- Path parameters must have
required: true. - For other locations,
requireddefaults tofalse.
So an existing parameter becomes breaking when required flips to true, or when it moves from query to header.
1. Get both versions
Take the spec from your last release, from a git tag or from the production docs endpoint, and the spec from your branch. JSON and YAML are both fine, and so are OpenAPI 3.x and Swagger 2.0.
2. Compare
Paste both into the free OpenAPI diff. Parsing happens on your device; YAML is read with the bundled js-yaml library. The tool reports:
- Breaking: removed endpoints, new required parameters, parameter type changes, request bodies that became required, removed responses, removed parameters and new deprecations.
- Non-breaking: new endpoints, new optional parameters and new responses.
Local $ref parameters are resolved.
3. Decide
- Fix accidental breaks before merge.
- For intended ones, version the API or announce a deprecation period.
- Add the change list to your release notes.
Know the limits
The browser tool does not compare response body schemas, external $ref files or security scopes. For those, or to fail a CI build automatically, use a CLI such as oasdiff. See the comparison guide.
Try it free: Free OpenAPI diff: breaking change checker
Paste the old and new OpenAPI (or Swagger) spec, in JSON or YAML, and get breaking and non-breaking changes in seconds.
Open the free tool →About the product: API Change Radar
The tool runs in your browser: your data stays on your device. No signup.
Sources
Venture Lab 10 is independent. Other product and service names are used only to describe compatibility or for comparison, and are trademarks of their owners.