minae

Posted on Jan 9 • Updated on Feb 17

Test Driving OpenAPI Documentation Generators (2024) - Part 1 of 3

#openapi #api #documentation #tooling

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).

Introduction
Test Drives

Introduction

Who might benefit from this article series ❓

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' ❓

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 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 ❓

This article will cover Redoc (started in 2016), Stoplight Elements (2019), and Rapidoc (2018).
The next article will cover Mintlify (2021), Readme (2014), Gitbook (2014), and Fern (2022).
The final article will cover Stoplight (2015), Swagger (2011), and Postman (2014).

Why these ten ❓

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. Postman hosts a detailed writeup of OpenAPI's history and evolution.

OpenAPI Description (OAD) files are plaintext files formatted as either JSON or YAML. Example snippet from an OAD file in 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. ✅
Able to publish public-facing docs on the free tier, if freemium. ✅
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. ✅

And that’s how I came to my final list. Some popular documentation generators were filtered out by my search parameters, such as Mkdocs and Docusaurus, 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
A way to run a development HTTP server on your local computer
An OAD (OpenAPI Description) file. Use your own or download my sample file, tasksapi.yml (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 Swagger PetStore specs and its corresponding live demo.

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

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

REDOC CODE

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

RAPIDOC CODE

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

STOPLIGHT ELEMENTS CODE

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

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.
Open a dev 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):

REDOC SCREENSHOT

Screenshot of browser open to localhost serving Redoc-generated documentation

RAPIDOC SCREENSHOT

Screenshot of browser open to localhost serving Rapidoc-generated documentation

STOPLIGHT ELEMENTS SCREENSHOT

Screenshot of browser open to localhost serving Elements-generated documentation

How to open a development HTTP server

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. 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 or live-server package:

npx live-server

If you have Python 3 installed, run its built-in http-server module on the command line:

python -m http.server

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

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:

Log in or sign up for a free account at Netlify.
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.)
Drag and drop your redoc, rapidoc, or elements folder where indicated.
Click Open production deploy.
You should see it live! The URL will will look something like https://6595eadb06abcb03854a869c--glowing-tartufo-dcb13c.netlify.app/
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/
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:

Final Notes

Details & comparison

	Redoc	RapiDoc	Elements
Offical Docs	Site	Site	Site
GitHub	Repo	Repo	Repo
GitHub Stars	21.7K	1.5K	1.3k
Year Started	2016	2018	2019
'Try It' Console	No, but available in Redocly	Yes	No, but listed on roadmap
Provided Examples	HTML, React	HTML, React, Vue	HTML, React, Gatsby, Angular, Bootstrap

Where to find live demos

Redoc demo
Rapidoc demos
Stoplight Elements demo
- 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 and Stoplight (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!

DEV Community