Test Driving OpenAPI Documentation Generators (2024) - Part 1 of 3
Tags: openapi, api, documentation, tooling
Published: 2024-01-09 06:12:11

---
title: Test Driving OpenAPI Documentation Generators (2024) - Part 1 of 3
published: true
series: Test Driving OpenAPI Documentation Generators
description: Quickstart tutorials for and discussion about generating API reference documentation from OpenAPI using the free, open-source tools Redoc, Rapidoc, and Spotlight Elements
tags: openapi, api, documentation, tooling
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x7akdj4jwrj9ig7v93lo.jpg
# Use a ratio of 100:42 for best results.
# published_at: 2024-01-08 09:57 +0000
---

In this article series, you will find a collection of introductions and quick-start tutorials for ten free and freemium OpenAPI documentation generators that create documentation webpages from OpenAPI Descriptions (OADs).

***
## Contents
   * [Introduction](#introduction)
      + [Who might benefit from this article series :question:](#who-might-benefit-from-this-article-series-question)
      + [What do I mean by 'test driving' :question:](#what-do-i-mean-by-test-driving-question)
      + [What documentation generators will this article series cover :question:](#what-documentation-generators-will-this-article-series-cover-question)
      + [Why these ten :question:](#why-these-ten-question)
   * [Test Drives](#test-drives)
      + [What to know before we ride](#what-to-know-before-we-ride)
      + [Requirements](#requirements)
      + [Part 1: Generate docs from OpenAPI](#part-1-generate-docs-from-openapi)
      + [How to open a development HTTP server](#how-to-open-a-development-http-server)
      + [Part 2: Make your docs viewable online](#part-2-make-your-docs-viewable-online)
      + [Final Notes](#final-notes)
         - [Details & comparison](#details-comparison)
         - [Where to find live demos](#where-to-find-live-demos)
         - [Usage notes](#usage-notes)
         - [Redoc vs Redocly and Stoplight Elements vs Stoplight](#redoc-vs-redocly-and-stoplight-elements-vs-stoplight)

***

## Introduction

### Who might benefit from this article series :question:

Reading this article series might be useful to you if you:
* are looking to publish online documentation using your OpenAPI definitions
* have already tried to publish your documentation with one of the generators in this article series and couldn't get it working
* are assessing the many OpenAPI documentation generators out there and trying to figure out their differences and suitability for a project

***

### What do I mean by 'test driving' :question:

I wanted to learn about a variety of OpenAPI documentation generator tools. I didn’t need to become an expert in any of them, only to get a feel for how each one works. 

I learn best by doing. I decided to run a series of basic 'test drives.' With each tool, I would:

- Use my own OpenAPI Description (OAD) file to generate browser-based API reference documentation.
- Publish the generated documentation online where anyone can view it.

In the [Test Drives](#test-drives) section below, I’ll show you exactly how I tried out each generator. I’ll tell you more of what I learned about these apps along the way. If you like, you can follow along and try them for yourself.

***

### What documentation generators will this article series cover :question: 
- This article will cover <a href="https://redocly.com/redoc/" target="_blank">**Redoc**</a> (started in 2016), [**Stoplight Elements**](https://stoplight.io/open-source/elements) (2019), and [**Rapidoc**](https://rapidocweb.com/) (2018).
- The next article will cover [**Mintlify**](https://mintlify.com/) (2021), [**Readme**](https://readme.com/) (2014), [**Gitbook**](https://www.gitbook.com/) (2014), and [**Fern**](https://buildwithfern.com/) (2022).
- The final article will cover [**Stoplight**](https://stoplight.io/) (2015), [**Swagger**](https://swagger.io/) (2011), and [**Postman**](https://postman.com/) (2014).

***

### Why these ten :question: 
I began with this question: *How can I generate browser-based API reference documentation for RESTful APIs?*

I looked for solutions that didn’t involve hand-coding and directly updating webpages. Web searches produced a plethora of approaches—Sphinx, Antora, Docusaurus, Madcap Flare, Swagger, Redoc, Readme, Slate, Stoplight, static site generators like Jekyll or Hugo with documentation themes, and so on.

I decided to focus on solutions that integrate OpenAPI 3+ out of the box without requiring third-party plugins. OpenAPI is the most widely used specification for standardized API descriptions. It's maintained by the [OpenAPI Initiative](https://www.openapis.org/). Postman hosts a detailed [writeup of OpenAPI's history and evolution](https://learning.postman.com/open-technologies/specifications/openapi/history/). 

OpenAPI Description (OAD) files are plaintext files formatted as either **JSON** or **YAML**. Example snippet from an OAD file in YAML:

```yaml
  /task/{id}:
    get:
      tags:
        - task
      description: Return a task based on its ID
      operationId: getTaskById
      parameters:
        - name: id
          in: path
          description: ID of task to get
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
```

Once you’ve described your API with OpenAPI, you can plug your OAD file into a tool that waves its magic wand and generates browser-based documentation from it.

So, what tool should I use for this? Dozens popped up on my radar, so I filtered my search further for solutions that are:

- Free OR freemium with a non-expiring free tier. :white_check_mark: 
- Able to publish public-facing docs on the free tier, if freemium. :white_check_mark: 
- Active. I checked websites, along with GitHub and NPM repo pages, for evidence of recent activity, maintenance, and community support. I also paid attention to general online buzz, from Reddit to Slack to StackOverflow to tech blogs and other forums. :white_check_mark: 

And that’s how I came to my final list. Some popular documentation generators were filtered out by my search parameters, such as [Mkdocs](https://www.mkdocs.org/) and [Docusaurus](https://docusaurus.io/), and I might write about them separately another time. Also on my radar are Writerside, Bump.sh, Doctave, Alphadoc, and Developerhub.io.

***

## Test Drives

### What to know before we ride

The three in this round—**Redoc**, **Stoplight Elements**, **Rapidoc**—are **free, open-source** tools. All the rest I test drove (with the exception of SwaggerUI) are SaaS (Software as a Service) products.

These three generate documentation locally on your computer, leaving the deployment up to you. The SaaS products do not offer that option; with them, your documentation is generated and deployed on their servers, and you must go through them to access your documentation files or to set up a custom domain.

The SaaS products also offer many benefits that the three in this round do not, such as analytics, hosting, user management, API design tools, and more. If such benefits are not as important to you as having complete control over your documentation, you will want to pay close attention to the three in this round. 

**Redoc** uses a **custom HTML element**, while **Stoplight Elements** and **Rapidoc** use **web components**. While there are differences between a custom HTML element and a web component, you'll use them more or less the same way.

Thus for this round only, I consolidated my ‘test drive’ steps for the three generators to avoid repetition. If you're following along, go through the instructions below three times, once per generator. 

***

### Requirements
- A code editor, such as [Visual Studio Code](https://code.visualstudio.com/) 
- A way to [run a development HTTP server](#how-to-open-a-development-http-server) on your local computer 
- An OAD (OpenAPI Description) file. Use your own or download my sample file, <a href="https://github.com/minaelee/tasksapi/blob/main/tasksapi.yml" target="_blank">tasksapi.yml</a> (right-click the link and choose _Save link as_). 

> Notes: If you'd like to have a more fully featured OpenAPI spec to play around with, check out the <a href="https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml" target="_blank">Swagger PetStore specs</a> and its corresponding <a href="https://petstore3.swagger.io/" target="_blank">live demo</a>.
> 
> Depending on the OAD file used, the 'try it' API consoles within the **Rapidoc**-generated documentation might or might not work. The `tasksapi.yml` file, for example, is a sample file with no live server defined for making API calls. I am not concerned with that functionality for these test drives. 

*** 

### Part 1: Generate docs from OpenAPI

1. Create a folder named `redoc`, `rapidoc`, or `elements` on your computer, depending on which generator you are testing.
2. Place a copy of your OAD file, such as `tasksapi.yml`, into that folder. 
3. In that folder, create a file named `index.html`.
4. Expand one of the below, then copy and paste the shown code into your `index.html`:

{% details **REDOC CODE** %} 
```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Documentation by Redoc</title>
    </head>
    <body>
        <redoc spec-url="tasksapi.yml"></redoc>
        <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">
        </script>
    </body>
</html>
```
{% enddetails %}

{% details **RAPIDOC CODE** %} 
```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Documentation by Rapidoc</title>
        <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js">
        </script>
    </head>
    <body>
        <rapi-doc spec-url="tasksapi.yml" show-method-in-nav-bar="as-colored-text">
        </rapi-doc>
    </body>
</html>
```
{% enddetails %}

{% details **STOPLIGHT ELEMENTS CODE** %} 
```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Documentation by Stoplight Elements</title>
    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
  </head>
  <body>
    <elements-api
      apiDescriptionUrl="tasksapi.yml"
      router="hash"
      layout="sidebar"
    />
  </body>
</html>
```
{% enddetails %}

5. If the OAD file you are using is *not* `tasksapi.yml`, then locate where `tasksapi.yml` is referenced in `index.html` and replace it with a reference to your own file.
6. [Open a dev server](#how-to-open-a-development-http-server) to view the generated documentation and confirm that it shows the API definitions from your OAD file. 

Example screenshots of what you should see (if using `tasksapi.yml`):
{% details **REDOC SCREENSHOT** %} 
![Screenshot of browser open to localhost serving Redoc-generated documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ya1eqtcyjvshhjjfwxwq.jpg)
{% enddetails %}

{% details **RAPIDOC SCREENSHOT** %} 
![Screenshot of browser open to localhost serving Rapidoc-generated documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5nxd7k381pacisdry2di.jpg)
{% enddetails %}

{% details **STOPLIGHT ELEMENTS SCREENSHOT** %} 
![Screenshot of browser open to localhost serving Elements-generated documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/k65mz6t3phky7f0hjf1y.jpg)
{% enddetails %}
   
*** 

### How to open a development HTTP server
{% details Instructions %} 
There are many ways to run a mock/test/dev server on your computer that simulates how your documentation will render when live online. 

If you use VS Code, you can use the [Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer). Once it's installed, right-click on `index.html` in the VS Code Explorer panel and choose `Open in Live Server`.

You can also run a dev server from the command line. The example commands below must be run from inside the `redoc`/`rapidoc`/`elements` folder):

- If you have **Node/NPM** installed, you can use the [http-server](https://www.npmjs.com/package/http-server) or [live-server](https://www.npmjs.com/package/live-server) package:

```bash
npx live-server
```

- If you have **Python 3** installed, run its built-in [http-server](https://realpython.com/python-http-server/) module on the command line:

```bash
python -m http.server
```

Afterward, read the CLI output for the local URL where you can view your files.
{% enddetails %} 

***

### Part 2: Make your docs viewable online

At this point, your documentation is only available on your computer. You can deploy them online as you would with any other static website. There are many free options for this. If you don’t have one you already prefer, you can follow these instructions for using Netlify:

1. Log in or sign up for a free account at [Netlify](https://netlify.com).
2. Click **Add new site** and choose to **Deploy manually**. (This is the simplest option for a quick throwaway demo; for a more permanent project, it's preferable to import your project from a git provider for continuous deployment.)
3. Drag and drop your `redoc`, `rapidoc`, or `elements` folder where indicated.
4. Click **Open production deploy**.
5. You should see it live! The URL will will look something like https://6595eadb06abcb03854a869c--glowing-tartufo-dcb13c.netlify.app/
6. If you want to use a custom subdomain name that's easier to read, change it under **Domain management** in the Netlify sidebar. For example, I changed the subdomain above to: [minae-elements.netlify.app/](https://minae-elements.netlify.app/)
7. If you want to use a custom domain, such as `docs.yourveryownsite.com` or `yourdocssite.com`, then you can follow Netlify’s instructions for doing so.

View my demo docs:
- [minae-redoc.netlify.com](https://minae-rapidoc.netlify.app/)
- [minae-rapidoc.netlify.com](https://minae-rapidoc.netlify.com)
- [minae-elements.netlify.com](https://minae-elements.netlify.com)

***

### Final Notes

#### Details & comparison
|  | Redoc | RapiDoc | Elements |
|---|---|---|---|
| Offical Docs | [Site](https://redocly.com/docs/redoc/) | [Site](https://rapidocweb.com/) | [Site](https://docs.stoplight.io/docs/elements/d6a8ba3f3c186-stoplight-elements) |
| GitHub | [Repo](https://github.com/Redocly/redoc) | [Repo](https://github.com/rapi-doc/RapiDoc) | [Repo](https://github.com/stoplightio/elements) |
| GitHub Stars | 21.7K | 1.5K | 1.3k |
| Year Started | 2016 | 2018 | 2019 |
| 'Try It' Console | No, but available in Redocly | Yes | Yes |
| Provided Examples | HTML, React | HTML, React, Vue | HTML, React, Gatsby, Angular, Bootstrap |

***

#### Where to find live demos
- [Redoc demo](https://redocly.github.io/redoc/)
- [Rapidoc demos](https://rapidocweb.com/list.html)
- [Stoplight Elements demo](https://elements-demo.stoplight.io/)
 - Try choosing different specs from the `Choose an example` dropdown for Stoplight Elements. At the time of this writing, the Box and Linode options are broken, but the others work.

***

#### Usage notes
- You can use the Redoc HTML element and the Rapidoc and Elements Web Components with vanilla HTML, or insert them into any framework, such as React and Angular. 

- The code for each `index.html` used in my drive tests uses scripts downloaded from CDNs (Content Delivery Networks). All three tools allow you to bypass using a CDN for entirely local code, if you need that option.
 
***

#### Redoc vs Redocly and Stoplight Elements vs Stoplight
Both Redoc and Stoplight Elements are the free, open-source projects of two SaaS products, [Redocly](https://redocly.com/) and [Stoplight](https://stoplight.io/) (also sometimes called the Stoplight Platform) respectively. I will test drive Stoplight in Round 3 of this series but not Redocly, as it does not offer a free tier with public-facing documentation. If you intend to subscribe to a paid tier of a SaaS product, you could still give Redocly a look for yourself!

***