Command-line and Go package to compare and detect breaking changes in OpenAPI specs.

Run it locally, in CI via the GitHub Action, or use the hosted PR review workflow at oasdiff.com to approve or reject each change with a CI commit status.

No install needed — try it with Docker against two sample specs:

docker run --rm -t tufin/oasdiff changelog \
  https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml \
  https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test5.yaml

That prints a human-readable changelog of every significant change between the two specs. Swap changelog for breaking to see only breaking changes, or diff for the full machine-readable diff.

go install github.com/oasdiff/oasdiff@latest

brew install oasdiff

The install.sh script downloads the latest oasdiff binary into /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh

To pin a specific version, set the version env var:

curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | version=1.11.7 sh

https://github.com/oasdiff/asdf-oasdiff

Pre-built binaries for macOS, Linux, and Windows (both x86_64 and arm64) are on the releases page.

Grouped by what you're trying to do. New to oasdiff? Start with Commands.

The six top-level subcommands.

• diff — full diff between two OpenAPI specs (output: html, json, markdown, markup, text, or yaml — default yaml)
• summary — high-level count of changes between two specs (built on the diff engine; same shared options)
• breaking — only breaking changes
• changelog — every significant change, breaking or not, in human-readable form
• flatten — replace allOf schemas with a merged equivalent
• checks — list the rules oasdiff uses to classify changes (customize them)

Where specs come from.

• Git revisions — compare against a branch, tag, or commit
• Local files, http/s URLs, YAML or JSON — all handled transparently

How oasdiff pairs up base and revision and what counts as a difference.

• Endpoint matching — handles renamed path parameters and duplicate endpoints
• Compare APIs split across multiple files — e.g. an API gateway with one spec per service
• Filter endpoints — narrow the diff to a subset of endpoints

Align each spec before diffing so equivalent things line up.

• Merge allOf schemas
• Merge common (path-level) parameters
• Path prefix modification — strip or add a prefix so a moved API still matches
• Case-insensitive header comparison — treat Content-Type and content-type as the same header

Communicate intent across versions.

• Deprecate APIs and parameters
• API stability levels (draft / alpha / beta / stable)

Choose which kinds of differences are reported.

• Exclude certain kinds of changes — e.g. ignore description-only edits
• Track OpenAPI extensions — opt in to reporting changes in x-* fields
• Exclude specific extension names — when extensions are tracked, skip ones you don't care about

Shape and enrich the report.

• Customize HTML and Markdown changelog templates
• Add OpenAPI-extension attributes to changelog entries
• Source location tracking
• Change fingerprints — stable IDs across commits
• Error reporting
• Localization: en, ru, pt-br, es

• Docker
• Configuration file
• Embed in a Go program
• GitHub Action for CI — and oasdiff.com for teams, which adds a per-change PR comment with approve/reject and commit-status checks

• OpenAPI 3.1 support — what's supported
• Security: control external $ref loading to prevent SSRF
• Usage examples — recipes for common scenarios
• Contributing

This project relies on the excellent implementation of OpenAPI 3.0 and 3.1 for Go: kin-openapi.

We welcome your feedback.
If you have ideas for improvement or additional needs around APIs, please let us know.