OpenAPI Diff Checker
Compare two OpenAPI specs and highlight breaking changes.
OpenAPI Diff Checker
Compares the real path/operation structure of both specs — not a canned example. Response/schema-level differences within an unchanged operation aren't detected yet.
Runs entirely in your browser
This tool executes locally using standard browser APIs (for example window.crypto.getRandomValues or crypto.subtle where applicable). Your input is not transmitted to or stored on a ScriptPulse server. See How Calculations Work.
What This Tool Does
- The OpenAPI Diff Checker compares two versions of an OpenAPI document — typically the previous and proposed contract for an API — and reports what changed between them, with particular attention to changes that would break existing consumers. Validating that a single document is structurally correct (what the OpenAPI Validator does) is a different question from whether a *change* to that document is safe to ship; a perfectly valid new spec can still remove a field, change a type, or make a previously-optional parameter required in a way that breaks every client built against the old version.
- This distinction matters most at exactly the moment an API evolves: a new endpoint being added is (usually) harmless to existing consumers, but a modified or removed one is not, and the difference between those two categories of change is precisely what a diff-focused tool is built to surface clearly, rather than requiring a manual side-by-side read of two full documents.
How It Works
- Two OpenAPI documents are provided — the baseline (previous) version and the candidate (new) version being considered for release.
- The tool compares the paths declared in each document to identify additions, removals, and modifications at the endpoint level.
- Newly-added routes and operations are reported as additive changes, generally safe for existing consumers since nothing they already depend on was altered.
- The comparison surfaces exactly what changed between the two versions, giving you the specific basis needed to judge whether a change is purely additive or potentially breaking for consumers built against the prior contract.
Usage
- Paste the baseline (previous) OpenAPI document.
- Paste the candidate (new) OpenAPI document.
- Run the comparison.
- Review the reported differences, paying particular attention to any removed or modified endpoint versus purely additive changes.
Examples
- Comparing last month's deployed API contract against this sprint's proposed changes to confirm no existing endpoint was altered in a breaking way.
- Generating a summary of newly-added endpoints for release notes after a feature addition that only introduced new, optional API surface.
- Catching an unintentionally removed endpoint during a refactor, before the change is merged and deployed to production.
- Reviewing a partner or vendor's proposed API update against their previous contract before agreeing to migrate your integration.
Real-World Use Cases
- Reviewing a proposed API change before release to confirm it's additive (new endpoints, new optional fields) rather than breaking (removed fields, newly-required parameters, changed types).
- Generating a human-readable summary of what changed between two API versions, for release notes or a changelog aimed at API consumers.
- Catching an accidental breaking change introduced during refactoring, before it reaches consumers who built against the previous contract.
- Comparing a currently-deployed OpenAPI document against a candidate update as part of an API governance or review process.
Best Practices
- Run a diff check as a standard step before any API release, not just when a breaking change is suspected — accidental breaking changes are often introduced without anyone intending them.
- Treat any removed field, removed endpoint, or newly-required parameter as a breaking change requiring a major version bump or a deprecation period, not a routine update.
- Use the diff output to write clear, specific release notes for API consumers — 'added POST /admins' is far more useful to a consumer than a generic 'various improvements' changelog entry.
- Pair diff checking with the OpenAPI Validator on both documents individually — confirming each version is structurally valid on its own is a prerequisite for a diff between them to be meaningful.
Common Mistakes
- Assuming any change that isn't a removed field is automatically safe — a newly-required parameter on a previously-optional field is just as breaking for existing consumers as removing something outright.
- Only reviewing a diff manually by reading two full documents side by side, missing a subtle single-field change that a dedicated diff tool would surface immediately.
- Treating an added endpoint as needing the same scrutiny as a modified one — genuinely additive changes carry much lower risk for existing consumers than anything touching an endpoint they already depend on.
- Skipping diff review entirely for what seems like a 'small' change, which is exactly the category of change most likely to introduce an unreviewed breaking modification.
Limitations
- This tool compares the paths declared in two OpenAPI documents to identify additions and structural differences; it does not perform a field-by-field deep schema comparison of every parameter and response type within each shared endpoint.
- It does not verify either document against a running API to confirm the real service's behavior actually matches what either document describes.
- Judging whether a specific reported change is actually breaking for your consumers still requires your own judgment about how your API is actually used — the tool surfaces what changed, not a certified safety verdict.
Technical Reference Guide
- The OpenAPI Specification, whose paths structure this comparison operates on, is maintained by the OpenAPI Initiative.
- What constitutes a 'breaking change' for an API contract is a widely-discussed API design and versioning practice rather than something the OpenAPI Specification itself formally defines or enforces.
- The underlying HTTP methods and semantics each compared operation represents are defined by RFC 9110.
Specifications & Standards
FAQ
What's the difference between this tool and the OpenAPI Validator?
The Validator checks whether a single OpenAPI document is structurally well-formed. This tool compares two documents against each other to identify what changed between them — a separate question from whether either one, on its own, is valid.
Is adding a new endpoint always a safe change?
Generally yes — a genuinely new endpoint doesn't affect consumers who weren't calling it before. The higher-risk changes are modifications or removals affecting endpoints that existing consumers already depend on.
What counts as a breaking change?
Common examples include removing a field or endpoint, changing a field's type, or making a previously-optional parameter required — any change that could cause an existing, unmodified client to fail or behave incorrectly against the new contract.
Does this tool tell me definitively whether a change is safe to ship?
It surfaces what changed between the two documents; whether a specific change is actually safe still depends on how your API is used in practice, which is a judgment call this tool informs but doesn't make for you.
Should I run this on every API change, even small ones?
Yes — small, seemingly minor changes are exactly the category most likely to introduce an unreviewed breaking modification, since they're the ones least likely to get careful manual review otherwise.
Can I use this output for release notes?
Yes — a diff between two API versions is a natural, accurate basis for writing specific, useful release notes for API consumers, rather than a vague summary of 'various improvements.'
Part of this Developer Hub
This utility is part of our comprehensive API & Web Engineering topic workspace.
Explore foundational guidelines, technical specifications, and other interactive utilities related to this workflow.
Related Tools
Explore related utilities inside the API & Web Engineering Lab workshop for complementary engineering workflows.
View all API & Web Engineering Lab tools