A Guide to Creating API Documentation With Redoc and GitHub Pages
Tags: documentation, api, webdev, tutorial
Published: 2023-03-02 13:44:13

### 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](http://localhost) but have no idea how to deploy it online to a static site hosting service like GitHub Pages, for example. The [quickstart](https://redocly.com/docs/cli/quickstart/) and [deployment](https://redocly.com/docs/redoc/deployment/intro/) 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](https://mich45.github.io/redoc-example/), and the complete code on [GitHub](https://github.com/Mich45/redoc-example).

### Prerequisites

To get started, ensure you have a [GitHub](https://github.com) account and the following installed on your computer:

* [Git](https://git-scm.com/)
    
* [Node.js](https://nodejs.org/en/)
    
* [Redocly CLI](https://redocly.com/docs/cli/installation/)
    

### 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](https://github.com/Redocly/openapi-starter).
    
2. Click on **Use this template**.
    
3. Select **Create a new repository**.
    

![Create repository GitHub](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/765msiqyek79mrbeqle2.png)

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.
    

    ![Code GitHub](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mr0qzzhzdkhxlvd8d26v.png )

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:
    

    ```bash
    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:
    

![Folder in VS Code](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yec2iz1p8q46fzcfoqnd.png )

### Step 3 - Install project dependencies

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

```bash
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](https://developers.forem.com/api/v1) on this page, or directly using [this link](https://developers.forem.com/redocusaurus/plugin-redoc-1.yaml). 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:

![YAML file in VS Code](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tayqia225mqpb977z3p5.png )

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:

```bash
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:

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

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

![Folder in VS Code](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0vg6z06p7zs3riees3t7.png )

#### `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:

```bash
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:

```bash
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`:

```bash
🪓 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:

```bash
redocly preview-docs bundled.yaml
```

You should get an output similar to this:

```bash
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`](http://localhost:8080) and you will see the documentation site rendered like below:

![Redoc documentation site](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y0cumfek8f21l5a8pcjm.png )

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:

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

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

```bash
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:

```html
<!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:

```bash
git remote -v
```

You should get an output similar to the following:

```bash
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:

```bash
git add .
```

Then run the following command to commit our changes:

```bash
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:

```bash
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:

![Live Redoc doc site](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ygpjc5y8v33aijpevr78.png )

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.
    

    ![Settings GitHub](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sqbxxuydqx2etuh1ouvm.png )

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

    ![GitHub Pages settings](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xhkaxzg3e8pd9sor3wcz.png)

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:
    

    ![Live Redoc site](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mky3inu3zm2xzpcrczlg.png )

Here’s a link to the static site generated for me on GitHub Pages: [https://mich45.github.io/redoc-example/](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:

![Live Redoc site](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4hv5pdhork1u2e48bj6u.png )

### 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!