I built my HTTP API docs from scratch

You might be thinking “building HTTP API docs from scratch? in 2024? wtf?”, and you’re probably right. After all redoc has been around since 2016, and there are hundreds of “generate beautiful documentation from your OpenAPI spec” startups around, some even use AI now.

To be honest, I didn’t even know it was possible to do-it-yourself when I started looking into it. Every search turned up with instructions on how to convert my OpenAPI schema into beautiful documentation via …some third party.

The thing is, I don’t want AI to answer questions about my product. If I can’t guarantee that it will be 100% accurate, it is useless to me. Similarly, I don’t want to put a third party in charge of displaying my API’s documentation to my users.

Frankly, third parties have no skin in the game when generating beautiful documentation. They seem to be more worried about selling to you, the one with the API, than to your users. Who cares if the docs are unusable? They’re beautiful! Have you seen our dark mode? /s

As a developer that started out on the frontend before learning backend and infra/ops, I thought I could do better, so I gave it a shot.

It only took 8 hours in the end, and I'm pleased with the results.

There were two steps:

• Converting OpenAPI schemas to markdown
  • Introducing widdershins
    • Customizing widdershins output
• Converting markdown to HTML

Converting OpenAPI schemas to markdown

I cheated a little bit, I didn’t handwrite an OpenAPI YAML schema from scratch (though I have in the past). My API of choice (HonoJS) provides a middleware for turning Zod validation into OpenAPI schemas, so I used that.

With an OpenAPI spec in hand, I needed a means of converting that data into markdown. Extensive searching came up with a weird word: widdershins.

Introducing widdershins

Widdershins was originally written to convert Swagger/OpenAPI specs to Slate/ReSlate compatible markdown using a templating language called doT.

I had no interest in using Slate/ReSlate, but since a templating language was involved, I knew I could grab the existing templates, fork them, and have them output MDX-compatible code instead.

Customizing widdershins output

Customizing the widdershins templates was a matter of cloning the widdershins repo, copying the files in templates/openapi3 into my own directory, and telling widdershins to use my templates instead of the default ones.

widdershins didn't do everything I wanted, but thankfully it was easy to customize the output.

Some hacks involved

• By default, widdershins outputs a single markdown file, so I had to insert placeholder text in my templates, and later use that to split the markdown by resource
  • Using an OpenAPI resource tag in my template, I then write the desired filename (checks/index.mdx for example) as the first line of the split markdown, and use that as my filename
• doT uses curly brackets for variables with no simple way of inserting curly brackets into output, so I had to use {{ and }} and run a markdownOutput.replace() to fix up my MDX

Converting markdown to HTML

As a developer, you're spoiled for choice these days when it comes to turning markdown/MDX into HTML. I was already a paying customer of Tailwind UI, so I chose to use their Protocol template (which uses Next.js under the hood), and modify it to my needs (mainly changes to the color-scheme and icon sizing).

I used Cloudflare's next-on-pages project so I could host the website on Cloudflare Pages, and not worry about being billed for bandwidth.

Summary

In short, it took me 8 hours to go from OpenAPI YAML file to my own custom HTTP API documentation website, and I'm very pleased with the results.

My main aim with this project was being able to have a say over every single aspect of the docs, so that I can react to my own customer feedback. If folks write in asking for extra details in certain places, or that something doesn't make sense, I'm capable of modifying the docs from the OpenAPI spec to the pipeline generating markdown, to the markdown renderer. I don't have to write to a vendor asking them to fix something, and have them tell me it'll be scheduled some time next quarter, maybe.