I talk to a lot of people about their API lifecycles and processes, and one thing that has value in almost every case is immediate documentation preview for all updates to an OpenAPI description. The time it takes to set it up (about ten minutes now I know what to do) is an investment that makes every future change easier to propose, review, and accept. Here’s my recipe for open source OpenAPI documentation using Redoc (disclaimer: I work for Redocly, who publish Redoc) with the files pushed to Netlify for hosting (but it’s HTML, so really any hosting will do and you should feel free to adapt the instructions for your preferred platform, and then share them in the comments).

OpenAPI in a GitHub repo

API documentation using OpenAPI assumes a docs-as-code workflow, and so does this post. You should have an OpenAPI description in a GitHub repository, so that when the description changes, the documentation can update. The big win here is that by adding preview builds for all pull requests, incoming changes can easily be shared and reviewed by all stakeholders, without any need to read YAML.

Tip: there’s no need to bundle the OpenAPI description to a single file, Redoc will follow references across files as needed so this approach is ideal for the during-development-and-review phase of the process.

Configure the Netlify project

The basic process, for Netlify or any equivalent, is to link the GitHub project to a deployable project so that updates run every time the repository updates. Netlify needs to know how to build the project, which in this case is generating the documentation as HTML, and what to publish. There’s a setting for “do this for pull requests as well” which is what makes the whole thing seem like magic!

Get started with the “Add new site” option and choose “Deploy with GitHub”. You may need to link your Netlify account to your GitHub account and/or the project you want to use if you haven’t used these tools together before or if you grant access on a per-project basis. Once that’s done, pick the project to generate API documentation for.

The next screen sets the site configuration. My project has openapi.yaml in the root folder, and my settings are like this:
* The build command is npx @redocly/cli build-docs openapi.yaml -o build/index.html.
* And publish directory is set to build/ since that’s where the previous command writes the files to.

Save the settings and the project will (hopefully) deploy successfully – don’t look away, it’s fast!

I’m not sure when Netlify started enabling preview deploys by default but that’s the behaviour in my most recent new site. Test your own setup by making a small but identifiable change to your API description, committing the change to a branch, and opening a pull request. After a few minutes the Netlify bot should comment with a link to the preview of the updated documentation.

All in all, the time investment to get a basic documentation rendering is definitely worth it (and if you need something more then I think I am contractually obliged to suggest you check out Redocly for the rest of the products). Investing in every stage of your API pipeline, from linting, to enrichment, and to docs – delivers rewards. And delivers them every time you make an API description change!

Hopefully you found this useful, I’d love to hear if you set this up yourself, or if you can share equivalent setups for other platforms so that others can learn from your wisdom: add a comment!