OpenAPI Diff & Breaking Change Checker

OpenAPI Diff compares a baseline and a candidate API specification by meaning, not by text. It matches operations by method and path (so /users/{id} and /users/{userId} are the same endpoint), resolves internal $ref references, and reports each contract change with its operation, location, before and after values, and why it matters to clients. Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 in JSON or YAML are supported, and Swagger 2.0 is normalized to the OpenAPI 3 shape first.

1. 1.Paste, upload or import the baseline spec (the version clients use today).
2. 2.Add the candidate spec (the proposed version).
3. 3.Select Compare.
4. 4.Review the Breaking, Warnings and Compatible tabs, and filter by method or area.
5. 5.Select a change to see the before and after values and why it matters.
6. 6.Copy the breaking changes for a pull request, or download the Markdown or JSON report for CI.

Requests and responses are judged in opposite directions. On the request side (what clients send), anything that narrows what is accepted is breaking: a new required parameter or property, a removed enum value, a changed type or format, a lower maximum or a higher minimum, a new pattern, or a removed content type. On the response side (what clients receive), anything that removes or widens what clients read is breaking or a warning: a removed property or success status, a changed type, a new enum value, or a required property that became optional. Removed endpoints, new authentication, changed security schemes and added OAuth scopes are breaking. Description, summary, title and example edits are documentation changes and are hidden unless you turn them on.

The comparison runs in your browser with a built-in rule engine; specs are never uploaded. URL import fetches the file directly from your browser without cookies, so servers that block cross-origin requests must be uploaded or pasted instead. Each spec can be up to 5 MB. External $ref files are reported but not fetched. Servers, callbacks, webhooks, links and vendor extensions are not compared, and the rules describe likely client impact rather than guarantee it: a strict or lenient server can behave differently.