oasdiff

Command-line tool 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.

Get started in 30 seconds

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 the changes that can affect API consumers, breaking and non-breaking. Swap changelog for breaking to see only the changes that break existing API clients, or diff for the full machine-readable diff of the API definition, including documentation-only edits.

Installation

Install with Go

go install github.com/oasdiff/oasdiff@latest

Install on macOS with Brew

brew install oasdiff

Install on macOS and Linux using curl

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

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.

Documentation

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

Commands

The top-level subcommands, grouped as in oasdiff --help.

Compare two specs

• breaking — only the changes that break existing API clients
• changelog — changes that can affect API consumers, breaking or not, in human-readable form
• diff — full diff of the API definition, including documentation-only edits (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)

Process a single spec

• validate — check a spec for per-RFC violations (invalid types, missing required fields, bad regex, unresolved $refs)
• upgrade — canonicalize an OpenAPI 3.0 spec to the latest 3.x
• flatten — replace allOf schemas with a merged equivalent

Git integration

• breaking-files — check a list of changed specs against their versions in a git ref, one comparison per spec; used by the pre-commit hook
• git-diff-driver — run as a git external diff driver so git log --patch renders an OpenAPI changelog inline

Reference

• checks changelog — list the rules breaking and changelog use to classify changes (customize them)
• checks validate — list the rules validate reports
• checks changelog coverage — list every possible edit of an OpenAPI document with the checks that cover it
• schema — print a JSON Schema for the breaking/changelog json output

Inputs

Where specs come from.

• Git revisions — 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 — handles renamed path parameters and duplicate endpoints
• Nullability changes — the three equivalent nullable forms and when changing them is breaking
• Compare APIs split across multiple files — e.g. an API gateway with one spec per service
• Check many independent specs — one comparison per spec, rather than merging them as composed mode does
• Filter endpoints — narrow the diff to a subset of endpoints

Normalization

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

API lifecycle

Communicate intent across versions.

• Deprecate APIs and parameters
• API stability levels (draft / alpha / beta / stable)
• Version bumps — report a breaking change released without a major version bump

Filtering changes

Choose which kinds of differences are reported.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗