Generating docs from OpenAPI Spec

It started with a very simple setup. Two github repositories: One for our backend, which included OpenAPI specs of our backend APIs. The second for our documentation website, which we based on Facebook's Docusaurus.

I chose Docusaurus for the docs website because about 500 of my closest friends recommended it. And it was a great choice - I could write docs using Markdown and not worry about anything else, Docusaurus magically turned them into a great looking website.

Until the point where we wanted to introduce generated API documentation to our docs. We wanted the generated docs to be integrated with the rest of the docs site. It should really feel like a single experience.

The first iteration involved adding a small build script to the docs repo that cloned the backend repo and used swagger-markdown on each file to generate markdown. Docusaurus found the markdown files and did the rest.

I wasn't super happy with the generated docs, but it worked for a while and we left it alone. Until Monday, when we merged a change that caused us to trigger a bug in swagger-markdown. The issue was reported more than 6 month back and has no responses. Which raised some concerns about whether it is a good project to depend on - very little activity, very few forks and stars... it didn't look good. 👎

So I did some shopping around. Here's what I tried, what worked and what didn't:

Widdershins 👎

This project looks fantastic. Tons of cool features, customizations and lots of github stars. But... I ran into this bug. The bug was fixed almost 2 years ago, but the project didn't have a single release since. I could have probably figured out a script that didn't require a release, but... this project is clearly just a single person who doesn't have time to do a release in two years. I didn't feel good depending on that either.

OpenAPI Generator 👎

This looked very official. The documentation wasn't great. When I tried it, it left a lot of "junk" in my working director. But the real problem was that it generated an entire directory structure of markdown for each input spec - and it seemed really painful to tie this into the main Docusaurus site. I could have probably made it work - but the minimal docs and messy experience got me to look around a bit more.

Redocusaurus ✅

This project was simple to install, simple to use, and was built exactly for my use-case. API docs in Docusaurus with a unified experience for users. It didn't have many github stars, but it wrapped the hugely popular redoc. And most important - the author is active, responsive and kind. Just check out the issues - he comes across as someone you want to work with. To put the icing on the cake - Forem, the engine behind this very website, uses this plugin. How cool is that?

I was all ready to use Redocusaurus, but there was one problem:

Our specs were split between several YAML spec files. It looked like a good idea when we did that - large files are not fun to work with. The problem is that very little in the OpenAPI ecosystem was built for multiple files. I strongly recommend that you will save yourself the pain and go the mono-file route. If Stripe can have a 4.5MB spec file, so can we.

In order to use Redocusaurus, I needed a single spec file. Both Swagger cli and OpenApi cli offered an option to merge separate specs into one. The problem was that one of them required a "root spec file" to drive the merging and the other required extra information to resolve conflicts. My specs had neither.

I ended up with an old fashioned solution - manually merging the spec files for now. Our engineering team has thoughts on how to improve our use of OpenAPI specs, and we'll have a better solution in a week or two as a result of that.

I hope this blog helps someone who has similar requirements or just tries to pick between 3 JS projects who all do similar things. Responsiveness of maintainers is really important.