https://github.com/oasdiff/oasdiff
OpenAPI Diff and Breaking Changes
https://github.com/oasdiff/oasdiff
breaking-changes changelog diff github-actions go golang openapi openapi-spec openapi-specification openapi-validation openapi-validator openapi3 openapi30 openapi31 rest-api side-by-side swagger
Last synced: 19 days ago
JSON representation
OpenAPI Diff and Breaking Changes
- Host: GitHub
- URL: https://github.com/oasdiff/oasdiff
- Owner: oasdiff
- License: apache-2.0
- Created: 2021-02-10T10:28:36.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2026-06-10T20:06:53.000Z (23 days ago)
- Last Synced: 2026-06-10T22:06:16.227Z (22 days ago)
- Topics: breaking-changes, changelog, diff, github-actions, go, golang, openapi, openapi-spec, openapi-specification, openapi-validation, openapi-validator, openapi3, openapi30, openapi31, rest-api, side-by-side, swagger
- Language: Go
- Homepage: https://www.oasdiff.com
- Size: 4.55 MB
- Stars: 1,233
- Watchers: 8
- Forks: 97
- Open Issues: 34
-
Metadata Files:
- Readme: docs/README.md
- License: LICENSE
- Security: docs/SECURITY.md
Awesome Lists containing this project
- awesome-integration - oasdiff (⭐1.2k) - Compare OpenAPI specs and detect breaking changes, with changelog generation in multiple output formats. (Projects / API Design)
README
[](https://github.com/oasdiff/oasdiff/actions)
[](https://codecov.io/gh/oasdiff/oasdiff)
[](https://goreportcard.com/report/github.com/oasdiff/oasdiff)
[](https://godoc.org/github.com/oasdiff/oasdiff)
[](https://hub.docker.com/r/tufin/oasdiff/tags)
Command-line tool to compare and detect breaking changes in OpenAPI specs.
Run it locally, in CI via the [GitHub Action](https://github.com/oasdiff/oasdiff-action), or use the hosted PR review workflow at [oasdiff.com](https://www.oasdiff.com) to approve or reject each change with a CI commit status.
## Get started in 30 seconds
No install needed — try it with Docker against two sample specs:
```bash
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.
## Installation
### Install with Go
```bash
go install github.com/oasdiff/oasdiff@latest
```
### Install on macOS with Brew
```bash
brew install oasdiff
```
### Install on macOS and Linux using curl
The [install.sh](../install.sh) script downloads the latest oasdiff binary into `/usr/local/bin`:
```bash
curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh
```
To pin a specific version, set the `version` env var:
```bash
curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | version=1.11.7 sh
```
### Install with asdf
https://github.com/oasdiff/asdf-oasdiff
### Download a binary
Pre-built binaries for macOS, Linux, and Windows (both x86_64 and arm64) are on the [releases page](https://github.com/oasdiff/oasdiff/releases/).
## Documentation
Grouped by what you're trying to do. New to oasdiff? Start with **Commands**.
### Commands
The top-level subcommands.
- [`diff`](DIFF.md) — full diff between two OpenAPI specs (output: html, json, markdown, markup, text, or yaml — default yaml)
- [`summary`](DIFF.md) — high-level count of changes between two specs (built on the diff engine; same shared options)
- [`breaking`](BREAKING-CHANGES.md) — only breaking changes
- [`changelog`](BREAKING-CHANGES.md) — every significant change, breaking or not, in human-readable form
- [`flatten`](ALLOF.md) — replace `allOf` schemas with a merged equivalent
- [`upgrade`](OPENAPI-31.md#converting-a-spec-with-oasdiff-upgrade) — canonicalize an OpenAPI 3.0 spec to the latest 3.x
- [`validate`](VALIDATE.md) — check a single spec for per-RFC violations (invalid types, missing required fields, bad regex, unresolved `$ref`s)
- [`checks`](CHECKS.md) — list the rules oasdiff uses to classify changes ([customize them](CUSTOMIZING-CHECKS.md))
- [`git-diff-driver`](GIT-DIFF-DRIVER.md) — run as a git external diff driver so `git log --patch` renders an OpenAPI changelog inline
### Inputs
Where specs come from.
- [Git revisions](GIT-REVISION.md) — compare against a branch, tag, or commit
- Local files, http/s URLs, YAML or JSON — all handled transparently
### Comparison
How oasdiff pairs up base and revision and what counts as a difference.
- [Endpoint matching](MATCHING-ENDPOINTS.md) — handles renamed path parameters and [duplicate endpoints](MATCHING-ENDPOINTS.md#duplicate-endpoints)
- [Compare APIs split across multiple files](COMPOSED.md) — e.g. an API gateway with one spec per service
- [Filter endpoints](FILTERING-ENDPOINTS.md) — narrow the diff to a subset of endpoints
### Normalization
Align each spec before diffing so equivalent things line up.
- [Merge `allOf` schemas](ALLOF.md)
- [Merge common (path-level) parameters](COMMON-PARAMS.md)
- [Path prefix modification](PATH-PREFIX.md) — strip or add a prefix so a moved API still matches
- [Case-insensitive header comparison](HEADER-DIFF.md) — treat `Content-Type` and `content-type` as the same header
### API lifecycle
Communicate intent across versions.
- [Deprecate APIs and parameters](DEPRECATION.md)
- [API stability levels](STABILITY.md) (draft / alpha / beta / stable)
### Filtering changes
Choose which kinds of differences are reported.
- [Exclude certain kinds of changes](DIFF.md#excluding-specific-kinds-of-changes) — e.g. ignore description-only edits
- [Track OpenAPI extensions](DIFF.md#openapi-extensions) — opt in to reporting changes in `x-*` fields
- [Exclude specific extension names](DIFF.md#excluding-specific-extension-names) — when extensions are tracked, skip ones you don't care about
### Output
Shape and enrich the report.
- [Customize HTML and Markdown changelog templates](CHANGELOG-TEMPLATE.md)
- [Add OpenAPI-extension attributes to changelog entries](ATTRIBUTES.md)
- [Source location tracking](SOURCE-LOCATOR.md)
- [Change fingerprints](FINGERPRINT.md) — stable IDs across commits
- [Error reporting](ERRORS.md)
- Localization: en, ru, pt-br, es
### How to run
- [Docker](DOCKER.md)
- [Configuration file](CONFIG-FILES.md)
- [Embed in a Go program](GO.md)
- [GitHub Action](https://github.com/oasdiff/oasdiff-action) for CI — and [oasdiff.com](https://www.oasdiff.com) for teams, which adds a per-change PR comment with approve/reject and commit-status checks
### Reference
- [OpenAPI 3.1 support](OPENAPI-31.md) — what's supported
- [Security: control external `$ref` loading to prevent SSRF](SECURITY.md)
- [Usage examples](USAGE_EXAMPLES.md) — recipes for common scenarios
- [Contributing](CONTRIB.md)
## Demo
## Credits
This project relies on the excellent implementation of OpenAPI 3.0 and 3.1 for Go: [kin-openapi](https://github.com/getkin/kin-openapi).
## Feedback
We welcome your feedback.
If you have ideas for improvement or additional needs around APIs, please [let us know](https://github.com/oasdiff/oasdiff/discussions/new?category=ideas).