The API DevTools space is alive and well with lots of new and exciting products popping up all the time. I’ve been especially impressed by the new tools in the docs space, but some of the options are less practical for use as quick human-friendly OpenAPI renderings or previews to use during API development. My current favourite in this space is Scalar because I can get an HTML file to easily include in a build or share with others. It’s a bit of a hack though, so I thought I’d share…

What I actually want here is a command that accepts an OpenAPI as an input and outputs a single HTML file as an output. Many of the modern docs tools think they need to start a local server and perhaps that’s useful for some use cases but it’s not a good developer experience for rendering a preview alongside some API design changes, for example. Other tools expect you to publish your OpenAPI file somewhere publicly, which is always a slow feedback loop and is sometimes not appropriate.

I found that Scalar supports adding OpenAPI into the HTML source and so I made a shell script that does the following:

• paste everything before where the HTML goes
• paste the OpenAPI file
• paste the rest of the HTML content
• save the whole lot as a file

Here’s the script:

#!/bin/bash

cat template_before.html openapi.yaml template_after.html > output.html

Have fun with your instant-but-hacky HTML preview of OpenAPI files, and thanks Scalar for making it easy!

You can add in configuration (the solarized theme looks SO GOOD in dark mode!) to suit your needs and preferences, and since we’re just using cat to put the files together, it’s FAST.

Enjoy your OpenAPI-to-HTML build process, and thank you to Scalar for making a great tool.