Markdown/Mermaid output for OpenAPI Arazzo

API reference documentation changed the way we built integrations, and eventually became part of the driving force for OpenAPI adoption and all the good tooling that flowed from it. As a developer experience specialist, I spend a lot of time thinking about how human users can work with the technical assets in a project. HTML-format API reference documentation does a great job of building that bridge when working on OpenAPI projects, but now I’m using Arazzo and it’s a very new standard with not nearly as many tools available for that format yet – so I built one.

ApiTapViz is a (very early stage!) Python CLI utility that helps humans to see what’s in an Arazzo file without having to read it raw. It picks out the summary data of the workflows and steps in an Arazzo file, and presents them to the user in either Markdown or Mermaid (diagram) format.

Flow diagram with title "Blog workflows". getCategories points to savePost which points to addImage

The idea is to make it simple to output a representation for users to quickly see how a flow works, or what’s covered in a particular workflow. It doesn’t have all the details that the Arazzo file has, but it could be useful to capture the output in internal (or external!) documentation, or as an artefact from a CI build.

Please try the tool with your Arazzo files, let me know how you get on, and get involved with the project on its (CodeBerg, there’s a GitHub mirror but only for discoverability) page: https://codeberg.org/lornajane/apitapviz


Also published on Medium.

One thought on “Markdown/Mermaid output for OpenAPI Arazzo

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.