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 · 300+ rules
| Severity | Change | Path | Review |
|---|---|---|---|
| 🔴 | response-property-removed | `GET /users` | ✅ Approved by @alice |
| 🔴 | request-parameter-type-changed | `GET /products` | ⏳ Review |
| 🟡 | response-optional-property-removed | `POST /orders` | ⏳ Review |
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- uses: oasdiff/oasdiff-action@v0.0.34
with:
base: base.yaml
revision: openapi.yaml
# Pro: post PR comment
- uses: oasdiff/oasdiff-action/pr-comment@v0.0.34
with:
base: base.yaml
revision: 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 →300+ breaking change rules
Most tools check a handful of obvious rules. oasdiff checks 300+ 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.
OpenAPI 3.1 support is in beta — try it and report issues.
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.