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

Roadmap

I am currently working on the ability to correlate breaking changes and changelog messages with the underlying changes in the original YAML spec.
This will allow users to see changes in their original context, investigate, and determine how to handle them.
Specifically, github users will be able to click annotations and see the diff at the relevant line as discussed here.
Please help us prioritize the roadmap.

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.