Detect Breaking Changes in OpenAPI Specifications
oasdiff compares OpenAPI specs and identifies every breaking change: endpoints removed, required fields added, response types changed, and over 300 more. Open source. CI-ready.
Supports OpenAPI 3.0 and 3.1 (beta).
★ 1,100+ GitHub stars · Apache-2.0 license · No account required
$ oasdiff breaking base.yaml revision.yaml
error [response-property-removed] at revision.yaml:38
in API GET /users
response property 'email' removed from status '200'
error [request-parameter-type-changed] at revision.yaml:15
in API GET /products
parameter 'limit' type changed from 'integer' to 'string'
2 breaking changes foundHow 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@main
with:
base: base.yaml
revision: openapi.yaml
# Pro: post PR comment
- uses: oasdiff/oasdiff-action/pr-comment@main
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 |
Catch breaking changes where you review code
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.
No context-switching to CI logs. No manually running oasdiff. The review happens where the code review happens.
See pricing →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.