Know exactly what changed in your API — and who approved it.
oasdiff posts a breaking change report on every pull request, with one-click approve/reject for each change. The CI gate updates automatically.
The CLI and GitHub Action annotations are free forever. PR comments and the approval workflow require oasdiff Pro.
★ 1,000+ GitHub stars · 1M+ downloads · 450+ rules
| Severity | Change | Path | Review |
|---|---|---|---|
| 🔴 | removed the success response with the status '200' | POST /api/v1/groups | ✅ Approved by @alice |
| 🔴 | request body property became required | POST /api/v1/orders | ⏳ Pending review |
| 🟡 | response body property became deprecated | GET /api/v1/users | — |
a3f9c12 · 📋 Review & approve changesHow teams use oasdiff
Works wherever your API lives — local, CI, or the browser.
# install
brew install oasdiff
# check for breaking changes
oasdiff breaking \
original-openapi.yaml modified-openapi.yaml
# generate changelog
oasdiff changelog \
original-openapi.yaml modified-openapi.yaml# Free: detect breaking changes
- uses: oasdiff/oasdiff-action/breaking@v0.0.40-beta.3
with:
base: original-openapi.yaml
revision: modified-openapi.yaml
# Pro: post PR comment
- uses: oasdiff/oasdiff-action/pr-comment@v0.0.40-beta.3
with:
base: original-openapi.yaml
revision: modified-openapi.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 →450+ breaking change rules
Most tools check a handful of obvious rules. oasdiff checks 450+ categories of breaking changes — every way an API modification can break an existing client, across every part of the OpenAPI spec.
Each rule 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.
What counts as a breaking change? →What counts as a breaking API change?
A breaking change is any modification that can cause existing client code to fail — without the client making any changes of its own. oasdiff detects all of them.
| Change | Breaking? | Why |
|---|---|---|
| Required request property removed | ✅ Yes | Clients that send it may get unexpected errors |
| New required request property added | ✅ Yes | Existing clients don't send it — requests fail |
| Response property removed | ✅ Yes | Clients reading that field will get null or crash |
| Response property type changed | ✅ Yes | Client type parsing will fail or produce wrong values |
| Endpoint path removed | ✅ Yes | All callers get 404 |
| HTTP method removed | ✅ Yes | All callers get 405 |
| Success response code removed | ✅ Yes | Clients checking for specific codes will break |
| New optional response property | No | Clients can ignore unknown fields |
| New optional request property | No | Clients that omit it still work |
| Endpoint description updated | No | Documentation only — no runtime impact |
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'
oasdiff fully supports OpenAPI 3.0 and 3.1, including the diff tool, GitHub Action, PR review, and online service. Learn more.
Swagger was the original name for what is now the OpenAPI Specification. If your spec file starts with openapi: "3., oasdiff supports it.
oasdiff resolves $ref references across files and reports the correct source location for each change, even in complex multi-file API definitions.