About openapi-changes

What is it and why does it exist?

---

In 2020, we built some internal OpenAPI tools for a mega tech corporation in silicon valley.

One of these tools was a ‘what changed’ type of library that would attempt to tell us what had changed in the latest release of an OpenAPI spec, and then render out those results to the API documentation (that we also built in-house).

The tool was flawed. The tool was inaccurate.

Take a look at an example of the original tool running in production right now!

The re-birth

Even though the tool was flawed and inaccurate and only partially complete, it was one of the more functional parts of the documentation for developers.

We wanted to reimagine the entire thing. The mega-corp code is not public and cannot be used - so we decided to start again from scratch, but with much better architecture, performance, capabilities, extensibility, user and developer experience.

openapi-changes is what we would have built, if we knew then what we know now.

Why not use what is already on the market?

There is nothing on the market like openapi-changes.

Some tools can detect breaking changes in OpenAPI contracts, some tools can tell you the differences found in a document, but none of them can do what openapi-changes can do.

Why is it different?

The tool has access to a full, hierarchical data model of every change, where it happened, and what was changed. The data model is provided by libopenapi.

openapi-changes uses this model to generate multiple different types of model renders, e.g., trees, graphs and indexes.

With re-rendered models, the tool can build out some beautiful and unique user interfaces that allow you to explore the changes in exciting and new ways that doesn’t exist anywhere else.

There is no other tool out there with an engine that programmatically creates a diff and maps it to a walkable OpenAPI, strongly typed model.

Back to the future

Another unique feature of the tool is that it can look back over the entire history of an OpenAPI specification, and tell you what has changed at every step of the journey and how many times the contract has broken, where and when.

It’s a time machine for your OpenAPI contracts that work out of the box with your git repository.

Integrated with GitHub

Feed the URL of an OpenAPI spec hosted on GitHub, for example, the OpenAPI Petstore Sample and openapi-changes will extract the history of the specification; no need to check out the repo.