Never ship a
breaking API change
by accident.
oasdiff turns every API change into a review on your pull request. It's code review, for your API contract. See exactly what changed, approve or reject each change, and block the merge until breaking changes are signed off.
The CLI, GitHub Action, and the shareable side-by-side review are free forever.
The approval workflow and audit trail are oasdiff Pro.
★ 1.3K GitHub stars · 13M+ downloads · 681 changes detected
API changes, reviewed like code
oasdiff brings the pull-request review you trust for code to your API contract.
Every possible change, decided
Why you can trust the verdicts.
Most tools detect breaking changes from a hand-curated list of rules: someone hit a case, wrote a check, and the list grew. The gaps are invisible until a client breaks.
oasdiff works from the other direction. We enumerated every field of the OpenAPI specification and every way each one can change: more than 15,000 possible edits. Every one of them is either covered by one of the 681 checks or excluded with a written reason. None are undecided, and the build fails if a new OpenAPI field appears that we have not classified.
Severities are not judgment calls either. One rule decides every verdict: a change is breaking if a request that was valid before can now be rejected, or a response can now carry something clients were never written to handle. Every check's severity is derived from that rule and enforced by tests, with zero exceptions.
So the promise is different in kind: no breaking change your contract can express gets through unnoticed. Breaking changes stop being accidents and become decisions, reviewed and approved by a person, or not shipped.
How teams use oasdiff
Works wherever your API lives — local, CI, or the browser.
# install
brew install oasdiff
# check for breaking changes
oasdiff breaking base.yaml revision.yaml
# generate changelog
oasdiff changelog base.yaml revision.yaml# Free: detect breaking changes
- uses: oasdiff/oasdiff-action/breaking@v0
with:
base: base.yaml
revision: revision.yaml
# Pro: post PR comment
- uses: oasdiff/oasdiff-action/pr-comment@v0
with:
base: base.yaml
revision: revision.yaml
oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}Paste two OpenAPI specs and get breaking changes, changelog, raw diff, or a side-by-side view — instantly, no install required.
Supports YAML and JSON. Results are processed server-side and not stored.
Open Diff Calculator →681 API changes detected
Most tools catch a handful of obvious cases. oasdiff detects 681 distinct changes, breaking and non-breaking, covering every way an API modification can affect an existing client, across every part of the OpenAPI spec.
Each change has an ID, severity level, and a detailed description of what changed and why it matters. Results include the exact file and line number of the change.
Review, approve, and unblock breaking changes
oasdiff Pro posts a single auto-updating comment on every pull request that touches your API spec — breaking changes at the top, organized by severity, linked to the exact line in the spec.
Each breaking change links to a hosted review page with a side-by-side spec diff. Approve or reject with a comment — the commit status updates automatically, and approvals carry forward when the branch is updated.
See pricing →removed the required response property 'email'
removed the required request property 'email'
Used by API teams at
Plus engineers from Adyen, Elastic, Palo Alto Networks, Wiz, HPE, Cvent, Starling Bank, Expedia, Apache Airflow, Cal.com, BeyondTrust, Box, Hitachi, and Hargreaves Lansdown.
oasdiff supports OpenAPI 3.0, 3.1 and 3.2 across the diff tool, GitHub Action, PR review, and online service. Upgrade a 3.0 spec online.
Swagger was the original name for what is now the OpenAPI Specification. If your spec file starts with openapi: "3., oasdiff supports it.
Compare an API split across many service specs in one run. oasdiff resolves $ref references across files and reports the correct source location for each change. Compare a microservices API.