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

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

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

Install with asdf

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

Manually install on macOS, Windows and Linux

Copy binaries from latest release.

Use install.sh

You can use the install.sh script to install oasdiff.
The script will download the latest version, or a specific version of oasdiff and install it in /usr/local/bin.

Try it

Locally

oasdiff changelog https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test5.yaml

With Docker

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

Features

• OpenAPI 3.1 support (beta)
• Source location tracking for inline PR annotations (beta)
• Detect breaking changes
• Display a user-friendly changelog of all important API changes
• Generate comprehensive diff reports including all aspects of OpenAPI Specification: paths, operations, parameters, request bodies, responses, schemas, enums, callbacks, security etc.
• Output reports in YAML, JSON, Text, Markdown, HTML, JUnit XML or the github actions annotation format
• Customize HTML and Markdown changelog reports
• Compare specs from local files, http/s URLs, or git revisions
• Compare specs in YAML or JSON format
• Compare two collections of specs
• Deprecate APIs and Parameters
• API stability levels
• Multiple versions of the same endpoint
• Merge allOf schemas
• Merge common (path-level) parameters
• Case-insensitive header comparison
• Path prefix modification
• Path parameter renaming
• Exclude certain kinds of changes
• Exclude specific extension names
• Track changes to OpenAPI Extensions
• Filter endpoints
• Extend breaking changes with custom checks
• Localization: view breaking changes and changelog messages in local languages: en, ru, pt-br, es
• Run with configuration file
• Run from Docker
• Integrate in GitHub
• GitHub Action
• OpenAPI Sync: Get notified when an API provider breaks the API
• Embed in your go program

Demo

The main commands

• diff: the diff between OpenAPI specs, fully detailed
• breaking: breaking changes between OpenAPI specs
• changelog: important changes between OpenAPI specs including breaking and non-breaking changes
• flatten: replace all instances of allOf by a merged equivalent
• checks: displays the different checks that oasdiff runs to detect changes

Roadmap

• OpenAPI 3.1 (beta)
• Source location tracking (beta)

Credits

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

Feedback

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