A Guide to Creating API Documentation With Redoc and GitHub Pages

Introduction

Redoc is a free and open-source tool for creating interactive API documentation from OpenAPI definitions. It's one of the most popular API documentation generation tools, with a three-column and responsive layout. Redoc is excellent for creating documentation sites and is simple to set up locally. However, deploying your local project online is often difficult and sometimes impossible, particularly for writers who have little or no technical experience.

Recently, I’ve had two people tell me that they were able to get their Redoc-generated site to work nicely on localhost but have no idea how to deploy it online to a static site hosting service like GitHub Pages, for example. The quickstart and deployment guides in the Redoc docs only explain how to run the generated docs locally and some of the information in the guides is not straightforward and beginner friendly.

This guide is my attempt to explain how I was able to publish an example API documentation site built with Redoc on GitHub Pages.

You can take a look at the deployed documentation we’ll be creating in this guide here, and the complete code on GitHub.

Prerequisites

To get started, ensure you have a GitHub account and the following installed on your computer:

• Git

• Node.js

• Redocly CLI

Step 1 - Create a copy of the openapi-starter template on GitHub

The first step in this guide will be creating a copy of the openapi-starter template on GitHub. The template is the recommended way to set up a Redoc project. It automatically creates the required folder structure and generates a basic OpenAPI definition file to try out what your final documentation site will look like.

1. Go to https://github.com/Redocly/openapi-starter.

2. Click on Use this template.

3. Select Create a new repository.

4. You’ll be taken to a page to create a new repository from the template.

5. Give the repository a name.

6. Choose whether you want the repository to be public or private.

7. Leave the Include all branches option unchecked.

8. Finally, select Create repository from template.

At this point, you should have a new repository created using the openapi-starter template and ready to roll!

Step 2 - Clone the repository to your computer

In this step, we’ll clone the Redoc project in the newly created repository so you can use it locally on your computer with Redoc CLI.

1. Click Code in the repository and copy the URL under the HTTPS tab.

   

2. Open your terminal and navigate to a directory where you’d like to clone your project.

3. Run the following command to clone the project:
   

   git clone <your-HTTPS-URL>
   

4. Cd into the cloned project directory and open it in your code editor. Your project folder should look like the image below:

Step 3 - Install project dependencies

Run the command below in the root of your project to install the dependencies required for using the template:

npm install

Step 4 - Prepare API definition file

If you open the openapi folder in the project root, you’ll see an openapi.yaml file that contains API definitions that we can use to create the documentation site. However, in this guide, we’ll use Forem’s OpenAPI definition file. You can download the definition file on this page, or directly using this link. If you have an OpenAPI specification file you would like to use, you're welcome to use that instead.

Next, open the openapi.yaml file and delete its content. Copy and paste the content of the Forem OpenAPI spec file you just downloaded into the openapi.yaml file. The file should look like below:

Now, in the openapi folder in your project root, you’ll see these three folders: code-samples, components, and paths. These folders are created when you run the redocly split command to separate the bundled API spec file into different parts, which allows for a multi-file approach to API documentation.

Since we already changed the contents of the openapi.yaml file, we need to delete these folders and create new ones since their contents are not identical to what we have in the new definition file. So, go ahead and delete those folders.

Step 5 - bundle, lint, and split

In this step, we’ll go through the different commands you'd need to prepare your definition file to create a Redoc-generated doc site running locally. It’s important that you understand what these commands do because you’re going to be using them most of the time when you’re working with a Redoc project.

bundle

The bundle command is used to merge all your standalone files into a single definition file and we can also use it to create a bundled version of our API definition file. It's basically the opposite of the spilt command.

In your terminal, cd into the openapi folder and run the following command to create a bundle of the openapi.yaml file:

redocly bundle openapi.yaml --output bundled.yaml

You should get an output similar to the following, and also a bundled.yaml file in the openapi directory:

bundling openapi.yaml...
📦 Created a bundle for openapi.yaml at bundled.yaml 333ms.

At this point, your folder structure should look something like below:

lint

The lint command checks if an API definition file is valid and conforms to OpenAPI specifications rules.

After creating a bundled.yaml file, we can now lint the file to check if it conforms to OpenAPI specification rules and contains no errors. In the terminal, ensure you’ve cd into the openapi folder, then run the command below to lint the bundled.yaml file:

redocly lint bundled.yaml

You should get an output in the terminal that says the definition file is valid.

split

The split command divides the large API definition file into different parts, allowing you to follow the multi-file approach to API docs.

Splitting the definition file will make it easier to work with different parts of your API definitions if your project becomes too large or complex.

Run the command below in the openapi directory to split the bundle.yaml file into its constituent parts:

redocly split bundled.yaml --outDir .

You should get an output similar to the following and two new folders created in the openapi directory, namely components and paths:

🪓 Document:  bundled.yaml is successfully split
    and all related files are saved to the directory: .

bundled.yaml: split processed in 1068ms

These folders let you work on different parts of your API definitions independently and seamlessly to improve your writing experience and help with managing large or complete documentation.

Step 6 - Preview the definition file locally

The last step in getting to view the documentation site locally is to run the preview-docs command to create a local preview of our API reference docs.

Run the following command in the openapi directory to create a local preview of the bundled.yaml file:

redocly preview-docs bundled.yaml

You should get an output similar to this:

Using Redoc community edition.
Login with redocly login or use an enterprise license key to preview 
with the premium docs.


  🔎  Preview server running at http://127.0.0.1:8080

Bundling...


  👀  Watching bundled.yaml and all related resources for changes  

Created a bundle for bundled.yaml successfully

Navigate to http://localhost:8080 and you will see the documentation site rendered like below:

Congratulations! We just made a local preview of our OpenAPI definition file with Redoc!

NOTE: The local server also allows you to make edits such as typo fixes to bundled.yaml and the changes will be reflected immediately in the preview site.

Step 7 - Preparing to deploy

Now that we have gotten our project to work locally, it’s of no use if we don’t get it live on a website for our users to see. However, deploying a Redoc project online is where most people get stuck.

But don’t worry, in this step, we'll go through how you can prepare your project for hosting on GitHub Pages. This is also going to work if you want to use GitLab Pages or any other alternative.

In the preview site we generated in the last step, note that we used the bundled.yaml file to create the preview. However, to create a documentation site we can deploy online, we’ll need to generate a *.json file from our openapi.yaml definition file. The JSON file is what Redoc will use to create our online static docs site.

In your terminal, cd into the docs folder in the root directory and run the following command:

redocly bundle ../openapi/openapi.yaml -o dist.json

You should see the following output and a dist.json file created in the docs folder:

bundling ../openapi/openapi.yaml...
📦 Created a bundle for ../openapi/openapi.yaml at dist.json 288ms.

Next, in the docs folder, delete the contents of index.html and paste the following code into it:

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

    <!--
    ReDoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='dist.json'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
  </body>
</html>

In the code above, the <script> tag fetches some JavaScript code from a CDN which will be injected into your documentation site when it’s deployed online. The code is responsible for rendering and generating the styling of your documentation site.

The <redoc> tag injects the bundled OpenAPI definition file into the site, and it’s also used by the JavaScript code to display our documentation site.

Step 8 - Deploying on GitHub Pages

In this final step, we’ll deploy the local preview of our project to a static site hosting service - GitHub Pages.

Navigate to your project root directory. Then run the following command to confirm your local project has the repository which we created in step 1 as the origin:

git remote -v

You should get an output similar to the following:

origin  https://github.com/Mich45/redoc-example.git (fetch)
origin  https://github.com/Mich45/redoc-example.git (push)

Next, run the command below to add all the changes we have made so far in the project to the staging area:

git add .

Then run the following command to commit our changes:

git commit -m ‘feature: publish docs to github pages’

Finally, run the command below to push your local changes to the template repository we created on GitHub:

git push origin

If you go back to the repository which we created in step 1, you should see that our local changes have been pushed to it. Here's what mine looks like:

So far so good.

Next, we'll generate a static docs site with GitHub Pages using this repository.

1. Click on the Settings tab in your repository as shown below.

   

2. In the left navigation bar, click on Pages.

   

3. In the drop-down menu under Source, select Deploy from a branch. Under Branch, select main, and under folder, select /docs.

4. Click Save.

5. Reload the page and you should see a link to your documentation site hosted on GitHub Pages as shown below:

   

Here’s a link to the static site generated for me on GitHub Pages: https://mich45.github.io/redoc-example/.

If you followed the steps above and everything went well, your static site should be up and running and identical to the image below:

Conclusion

Viola! That’s it. In this guide, we went through how you can setup and run a Redoc project locally, and also how to deploy a professional-looking Redoc-generated documentation to GitHub Pages.

I hope you found this guide useful for deploying your Redoc-generated sites to GitHub Pages.

Adios, until next time!

Comments

[Daniel Ma]

I appreciate how you emphasize the importance of streamlined workflows! EchoAPI makes managing API documentation so straightforward, allowing me to focus more on coding rather than paperwork.