You’re probably thinking, “wow what a boring name”.
I know it’s boring. It’s also the best thing I could come up with.
All the other tools with similar functionality (but nowhere near as sexy) had already taken all the variations I could come up with.
So, I named it literally. Boring, but practical! Like a minivan.
So what is it?
A new tool from pb33f that I created. Essentially, it’s a time machine that allows you to discover what has changed between two versions of an OpenAPI contract.
Boring, who cares?
Diffing a file is boring, yes. It’s also confusing at times. And that’s where openapi-changes changes the game. It provides innovative ways to visualize what has changed and how the contract has changed with each commit to a git repository.
A long time ago, in a galaxy far away
Well, it wasn’t that long ago or very far away. It was 2020, and it was Palo Alto, California.
Teams using the tooling I created at VMware wanted a changelog functionality when publishing OpenAPI specs. Well, at least that’s what they thought they wanted.
What they actually needed, however, was a tool to determine the changes for them and print a nicely rendered report.
Under the covers, we had built a library called wch, which stood for ‘what-changed.’ Unfortunately, the library was not very friendly to use, and it was quite a bit of work to wrangle it into another tool I had created, called the printing press.
The printing press generates OpenAPI documentation from OpenAPI contracts. Now, it could create a changelog by reading a left and right model and determining what had changed using wch.
Take a look at the result. It’s not too bad.
Except it is bad.
wch is quirky, inaccurate, buggy, and complex. Given the option, it’s something other than what I would want to use.
It’s not an option anyway, none of the code is open-source. It’s proprietary.
So, I rebuilt the tool from the ground up but with a much cleaner and unified design. The brains for openapi-changes live in libopenapi.
The logic for determining what changed and building out a walkable dataset lives there, so any engineer can use it to build their own experiences for that data.
openapi-changes builds on that model from libopenapi and then adds some unique user experiences.
Changes as a tree
An OpenAPI document is a tree data structure, and it’s also a very well-defined tree structure. Every branch and leaf is supposed to be there and is trackable.
It’s much easier to see the depth of a difference when you can visually see where in the network it changed.
openapi-changes brings an explorable tree of changes that makes it easy to see where something happened in the model vs. a flat list.
Changes as a graph
If a tree is still too confusing to understand, what about rendering out changes as an explorable visual graph?
This view takes the same result set, but this time renders it into a visual graph of the changes discovered between two documents.
The interactive visualization can pan and zoom and be re-drawn with flow moving in a different direction.
These two modes of exploration generally differ from what you see on these types of tools, and the reports are usually dry and un-sexy.
As you can see, I aim to change that.
Changes as a report
Like data? Want a machine-readable version of the change report? No problem. openapi-changes can generate a JSON report quickly, which is the same data that powers the other UIs, is the same data in the report.
Back to the future
openapi-changes comes with another innovative feature. It allows you to travel back in time.
Review how a specification has changed, with each commit available as a point in time to see what changed.
openapi-changes references the HEAD version against the previous commit and compares every commit to its predecessor.
The git integration makes it easy to see how things look over time, unlike a single snapshot.
Face/Off
openapi-changes offer multiple interface options.
You have already seen some examples of the html-report; however, a CI/CD-friendly summary view provides a terminal output that is easy for diagnostics in a pipeline and a terminal for local development.
Terminal UIs are cool.
Are you old-school like me and love a fast, light, terminal UI instead of always needing a browser?
openapi-changes comes with a super simple but fully featured terminal UI, all the same data available in the html-report, just explorable from a terminal window.
Github friendly
openapi-changes comes with support for Github out of the box. There is no need to check out the entire repository; point at the repo, and the tool will do the rest!
Take a quick tour.
If you’d like a quick tour of the tooling, I have created a short tutorial that walks through its basic functionality and how to use it.
Try the online demo; nothing to download, and get a taste of how it operates.