Detect OpenAPI breaking changes before release

Compare two OpenAPI specs locally and flag breaking changes such as removed paths, removed methods, required fields, or changed response schemas.

Open this example in OpenAPI Diff

Open the tool, then paste the sample input below. Everything runs locally in your browser.

Open this example in OpenAPI Diff →

The problem

A small OpenAPI edit can break clients when a path disappears, a request field becomes required, or a response type changes. Diffing the old and new specs before release gives reviewers a focused checklist.

Sample input

Old and new OpenAPI fragments
Old: GET /users/{id} returns 200 User
New: GET /users/{id} removed; GET /members/{id} added

Expected output

Breaking change summary
Breaking: removed operation GET /users/{id}
Non-breaking: added operation GET /members/{id}

How to do it

  1. Paste the current OpenAPI spec.
  2. Paste the proposed OpenAPI spec.
  3. Run the analyzer.
  4. Review breaking and non-breaking changes separately.
  5. Share the summary with API reviewers.

Common mistakes

  • Only checking endpoint names and missing schema changes.
  • Treating added required request fields as safe.
  • Ignoring removed enum values.
  • Comparing formatted YAML without semantic checks.

Related tools

FAQ

What counts as an OpenAPI breaking change?

Removed paths, removed methods, stricter request requirements, and incompatible schema changes are common breaking changes.

Can added endpoints be breaking?

Usually no, but added required fields or changed behavior on existing endpoints can be breaking.

Are my OpenAPI specs uploaded?

No. The comparison runs locally in your browser.

Is my data uploaded anywhere?

No. This workflow runs locally in your browser unless you explicitly copy or share the result yourself.

This guide uses browser-local tooling. Avoid pasting production secrets unless you understand what the tool displays and shares.

Explore related tools

Continue with adjacent browser-based tools for the same workflow.

View JSON and API contract tools →

Detect breaking OpenAPI changes: quick answer

Use this before publishing a new API spec, bumping a version, or regenerating client SDKs. Paste or load the artifact into the linked tool, run the local check, then copy only the safe result or summary into your PR, ticket, or test notes.

What to verify

Review removed paths, required fields, enum narrowing, auth changes, status code changes, and response schema changes. If a result will be shared outside your team, run a privacy or secret scan first and replace real values with safe examples.

Recommended next steps

Practical example and expected result

Compare two OpenAPI specs locally and flag breaking changes such as removed paths, removed methods, required fields, or changed response schemas. In practice, this is most useful when you need a quick, repeatable check on a OpenAPI spec before adding it to a ticket, pull request, test fixture, or support note.

A realistic input for this workflow is Old: GET /users/{id} returns 200 User New: GET /users/{id} removed; GET /members/{id} added. The expected result should resemble Breaking: removed operation GET /users/{id} Non-breaking: added operation GET /members/{id}, with the same important values preserved.

Troubleshooting checklist

  • Confirm you copied the complete OpenAPI spec and not only a partial line or truncated preview.
  • Run the local tool once with a safe sample, then repeat with the real data only if your team policy allows it.
  • Check quoting, escaping, whitespace, encoding, timestamps, and environment-specific values before trusting the result.
  • Before sharing output, remove secrets, tokens, cookies, customer data, and production hostnames that are not needed for the review.

Next useful steps