How to publish ReDoc (OpenAPI) documentation on GitHub Pages
Soon after learning about the convenience and ease-of-use of ReDoc, I started writing the documentation for a REST API following the OpenAPI Spec. Once I was done, the next big question came up: can I host the deployed documentation on GitHub Pages? The answer is yes (why would I be writing this article otherwise, right?), and the process is, in fact, quite simple.
What this article is not
This article assumes that you have all your ReDoc/OpenAPI related files ready, and that you are able to build them locally (i.e., these files don’t contain errors). It also assumes that you know how to set up GitHub Pages. If this is your case, you can safely skip to the next section.
Otherwise, if you need some help getting started with Redoc/OpenAPI, here are two useful links:
- Redoc.ly Docs: unsurprisingly, the best point to start from.
- OpenAPI Spec: here you can find the OpenAPI Specification, which provides you with the building blocks to easily document your app.
As usually, some examples might be helpful. Here you can find quite some of them (shout-out to APIs-guru). Most of these examples follow a single-file approach, i.e., the whole documentation is contained in one file. This file can actually get huge as your API grows over time.
That’s why the ReDoc team recommends that you separate your documentation into multiple files, which makes things much easier to maintain. For a simple example, you can check out the API Docs that I wrote (sorry for the egocentricity, I just couldn’t find any good examples for this multi-file approach; if you know any, please drop me a comment).
Alright, enough for now. Let’s get down to business, that is, the actual topic of this article.
Steps to host your ReDoc Docs on GitHub Pages
1st: Bundle the docs into a zero-dependency HTML file
Thanks to redoc-cli, this can be easily done by running a single command. You can either install the client, or use directly npx without having to install anything. I personally prefer this second option, since you just need to run:
npx redoc-cli bundle <path-to-root-spec-file>
For example, if you named your root OpenAPI spec file openapi.yamlthen you would run:
npx redoc-cli bundle openapi.yaml
If you have installed the client, just remove npx from the previous command.
This will generate a single html file called redoc-static.html, which is a static, fully-functional version of your built documentation. As far as I know, there’s not any option of customizing this filename directly from the client, so you can rename it manually, or just run:
mv redoc-static.html index.html
Another thing I couldn’t figure out how to do using redoc-cliwas to make the favicon work: after running the command, it was missing in the html. I would say this could actually be a bug. Someone mentioned it on the ReDoc repo, and got a possible workaround. I find it simpler to just add it manually to the index.html or, what’s faster, run:
sed -i '7 i \ \ <link rel="icon" type="image/png" href="path_to_favicon"/>' index.html
This will add the necessary html code to include the favicon in the 7th row of the file, with 2 spaces of indent.
2nd: Activate GitHub Pages on your repo and push the index.html
The file generated in the previous step is all we need to publish our API Docs on GitHub Pages.
You can just push it and activate GitHub Pages in your repository… And that’s it! Your nice-looking API documentation will be up and running. This is an example of how it will likely look like:
Bonus: Automatically deploying the documentation
At this point, we can go one step further and add a GitHub Action to deploy the docs every time any change is pushed to the repository.
To do this, we can use the always-useful actions-gh-pages action. This is how I set it up (you may have to adapt it to your needs):
The first yaml file configures the action. What it basically does is: whenever a push to main is made, it runs make.sh (which performs all the steps to build the docs, as mentioned previously), and pushes the result to a branch called gh-pages, excluding the files that are not relevant to GitHub Pages. If you have a custom domain, don’t forget to set the cname field or else the domain will be removed from your GitHub Pages configuration every time the action is run.
That’s a wrap! I hope you found this article useful. If you have any suggestions, comments, or there’s something I didn’t get quite right, please don’t hesitate to tell me. Thank you and happy ReDoc-ing!
