OpenAPI Diff, or Oasdiff for short, is an open source utility that takes comparing OpenAPI specs to identify breaking changes to a whole new level.
The consensus is that despite have a multitude of tools available nowadays, designing and maintaining an API is still not an easy task to perform. One of the aspects that causes problems is the dreaded "breaking change". Why is that? Let Oasdiff main implementer and Tufin CTO, Reuven Harrison, explain:
What is a breaking change? A breaking change is a change to a component, such as a server, that could break a dependent component, such as a client, for example deleting an endpoint. When working with OpenAPI, breaking-changes can be caught by monitoring changes to the specification.
Why check for Breaking Changes? Detecting breaking changes in OpenAPI is an effective way to avoid downtime and maintain business-continuity, especially for complex applications that involve many APIs, multiple services, large or distributed development teams or undergo frequent changes.
A diff tool can be used to track changes made by developers to APIs, understand their context and impact, provide documentation for API consumers who want to track functionality changes including bug fixes and upgrade paths, and most importantly, to detect breaking-changes and even prevent them.
OpenAPI Diff is a tool that can make that task easy to perform, offering a Java library, a CLI utility, even an online playground for manual comparison, as well as a webservice which you can Curl. It also integrates with the CI/CD pipeline, hence catering for every need and environment out there.
This last part on the CI/CD pipeline is and the most important since automated checking that can detect non-trivial breaking-changes can help to prevent downtime. As such, users can run oasdiff in their CI/CD pipeline as a docker image or a cmd-line to test for breaking-changes and/or break the build on certain conditions. For Github specifically there is also a GitHub action.
The tool's main features are :
Detecting breaking changes
OpenAPI diff in YAML, JSON, Text/Markdown or HTML
Display a user-friendly changelog of all important API changes
Run from Docker
Embed in your go program
OpenAPI diff of local files system or remote files over http/s
Compare specs in YAML or JSON format
Compare two collections of specs
Comprehensive diff including all aspects of OpenAPI Specification: paths, operations, parameters, request bodies, responses, schemas, enums, callbacks, security etc.
API deprecation
Path prefix modification
Path parameter renaming
Excluding certain kinds of changes
Excluding endpoints
Extending breaking-changes with custom checks
Localization
Additional improvements in oasdiff’s newest version's breaking-changes:
human readable output
supports localization for error messages and ignored changes
checks can be modified by developers using oasdiff as a library with their own specific checks by adding/removing checks from the slice of checks
ability to ignore certain changes with a configuration file
support for stability-levels which allows breaking-changes in early development phases like draft and alpha but not later in beta and stable
fewer false-positive errors by design
improved support for type changes: allows changing integer->number for json/xml properties, allows changing parameters (e. g. query/header/path) to type string from number/integer/etc.
allows removal of responses with non-success codes (e. g. , 503, 504, 403)
One last thing though. How does it compare to the official OpenApi diff utility? Here's a detailed comparison chart that highlights the differences:
oasdiff
OpenAPITools/openapi-diff
Stack
golang
Java
Docker image size
< 7 MB
> 80 MB
Diff
Deep and comprehensive. Catches every kind of change.
Shallow and partial.
Ignores some kinds of
changes.
Diff files from local file
system
Yes
Yes
Diff remote files from http
Yes
No
Output
json
yaml
text
markdown
html
json
text
markdown
html
Colorized Output
Yes
No
Diff between multiple specs (using globs)
Yes
No
Breaking Changes
Full with > 100 checks.
Specifies exact breaking changes in human-readable language.
Partial (# of checks
unknown).
Only tells you whether there were any breaking changes, doesn't specify the exact breaking-changes.
Deprecation policies
Yes
No
Ignore Specific Breaking Changes with Configuration
Yes
No
Localization
Yes
No
In conclusion, Oasdiff's approach to preventing breaking changes is a solid attempt to help in designing and maintaining APIs, as such earning itself a place in the developers' arsenal of most valuable tools.
JDK 22 is not a Long Term Support release, but is one of the regular releases that are scheduled to arrive every six months. Still, it has got a lot to show for itself.
