What an OpenAPI diff catches
Because it compares structure, a spec diff is good at contract-level breaking changes:
- Removed paths, operations, parameters or response properties.
- Parameters that became required, or request properties that became required.
- Type and format changes on parameters and schemas.
- Removed enum values and narrowed constraints.
- Changed or removed response status codes and media types.
Open-source tools
- oasdiff is a Go command-line tool and library that compares OpenAPI specs and reports breaking changes, with a Docker image and a GitHub Action. It can emit text, Markdown, JSON or HTML.
- openapi-diff is a Node.js tool that classifies differences and exits with a non-zero code when it finds breaking changes, which makes it easy to fail a build.
Check each tool’s documentation for OpenAPI 3.1 support and for the exact list of rules it treats as breaking; they differ.
Example: fail a pull request on breaking changes
The pattern is the same with any tool: check out the base branch’s spec, compare it with the PR’s spec, and fail on breaking differences.
# .github/workflows/api-diff.yml
name: API breaking changes
on: pull_request
jobs:
diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- run: git show origin/${{ github.base_ref }}:openapi.yaml > base.yaml
- run: |
docker run --rm -v "$PWD:/specs" tufin/oasdiff \
breaking /specs/base.yaml /specs/openapi.yaml --fail-on ERRWhat a spec diff cannot see
- Spec drift. The diff only knows what the document says. If the implementation and the spec disagree, the diff is checking fiction.
- Behavioral changes. Units, defaults, ordering, rounding and business logic can change while the schema stays identical.
- Consumer impact. A diff tells you something changed, not which customers call it or what their code does with the result.
That is why spec diffing is the first layer, not the last. The next layer exercises the real implementation: replaying recorded traffic against the old and new versions and comparing complete responses. See traffic replay testing.
Frequently asked questions
What is an OpenAPI diff?
A comparison between two versions of an OpenAPI document that lists added, removed and changed paths, parameters and schemas, and classifies which differences are breaking for existing clients.
Can an OpenAPI diff catch every breaking change?
No. It catches structural, contract-level changes described in the spec. It cannot see behavioral changes that keep the schema identical, or differences between the spec and the real implementation.