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
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
, orelements
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 wheretasksapi.yml
is referenced inindex.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
):
How to open a development HTTP server
If you use VS Code, you can use the Live Server extension. Once it's installed, right-click on You can also run a dev server from the command line. The example commands below must be run from inside the Afterward, read the CLI output for the local URL where you can view your files.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.
index.html
in the VS Code Explorer panel and choose Open in Live Server
.redoc
/rapidoc
/elements
folder):
npx live-server
python -m http.server
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
, orelements
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
oryourdocssite.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 | Yes |
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.
- Try choosing different specs from the
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!
Top comments (0)