Repository files navigation

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

go install github.com/oasdiff/oasdiff@latest

brew tap oasdiff/homebrew-oasdiffbrew install oasdiff

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

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

Copy binaries fromlatest release.

You can use theinstall.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.

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

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

• Detectbreaking changes
• Display a user-friendlychangelog of all important API changes
• Generate comprehensivediff reports including all aspects ofOpenAPI Specification: paths, operations, parameters, request bodies, responses, schemas, enums, callbacks, security etc.
• Output reports in YAML, JSON, Text, Markdown, HTML, JUnit XML or thegithub actions annotation format
• Customize HTML and Markdown changelog reports
• Compare local specs or remote specs over http/s
• 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
• 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
• Run as a Service
• OpenAPI Sync: Get notified when an API provider breaks the API
• Embed in your go program

• 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

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 discussedhere.
Please help us prioritize the roadmap.

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

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