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

Installation

Install with Go

go install github.com/tufin/oasdiff@latest

Install on macOS with Brew

brew tap tufin/homebrew-tufin
brew install oasdiff

Install on macOS and Linux using curl

curl -fsSL https://raw.githubusercontent.com/tufin/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

Try it

Locally

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

With Docker

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

Features

• 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
• Compare local files or remote files over http/s
• Compare specs in YAML or JSON format
• Compare two collections of specs
• API deprecation
• API stability levels
• Multiple versions of the same endpoint
• Merge allOf schemas
• Merge common parameters
• Case-insensitive header comparison
• Path prefix modification
• Path parameter renaming
• Excluding certain kinds of changes
• Tracking changes to OpenAPI Extensions
• Filtering endpoints
• Extending breaking changes with custom checks
• Localization: display breaking changes and changelog messages in English or Russian (please contribute support for your language)
• Customize with configuration files
• Run from Docker
• Integrate in GitHub
• GitHub Action
• Cloud Service
• 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

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.