Test Driving OpenAPI Documentation Generators (2024) - Part 2 of 3
Tags: openapi, saas, documentation, tooling
Published: 2024-01-22 05:37:44

---
title: Test Driving OpenAPI Documentation Generators (2024) - Part 2 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 SaaS documentation platforms ReadMe, GitBook, Mintlify, and Fern
tags: openapi, saas, documentation, tooling
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kl2dtl9exu1zxpih3yn4.jpg
# published_at: 2024-01-12 20:49 +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).

Ready for another round of test drives? 
If you didn't catch the [first article](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7) in this series, check out at least its [Introduction](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7#introduction) to get up to speed. Pun intended.

***
## Contents
* [Preliminaries](#preliminaries)
     + [What are we test driving :question:](#what-are-we-test-driving-question)
     + [What should I know about them first :question:](#what-should-i-know-about-them-first-question)
     + [Requirements for all four test drives](#requirements-for-all-four-test-drives)
     + [Mintlify and Fern requirements](#mintlify-and-fern-requirements)  
* [The test drives](#the-test-drives)
     + [GitBook](#gitbook)
     + [ReadMe](#readme)
     + [Mintlify](#mintlify)
     + [Fern](#fern)
* [Coming up](#coming-up)

***

## Preliminaries
&nbsp;<br />

### What are we test driving :question:
This round, we're taking [GitBook](https://gitbook.com) (started in 2014), [ReadMe](https://readme.com) (2014), [Mintlify](https://mintlify.com) (2021), and [Fern](https://buildwithfern.com) (2022) for a spin. 

***

### What should I know about them first :question:
The three options that I test drove in the [previous round](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7) (Rapidoc, Redoc, and Spotlight Elements) were single-purpose tools to generate self-hosted API reference documentation from **OpenAPI Descriptions (OADs)**.

The four in this round are **Software as a Service (SaaS)** products. That means they are **subscription-based cloud services** and cannot be self-hosted. All four can be used to create not only API references but other types of documentation, such as tutorials and guides. All four provide a non-expiring free tier that allows you to generate public-facing documentation on their servers. Each offers a different feature set from the others, with overlap. 

For example, **GitBook** can publish documentation as ebooks. **ReadMe** comes with native discussion forums. GitBook, ReadMe, and **Mintlify** all have built-in WYSIWYG editors for creating and modifying documentation online, whereas Fern does not. **Fern** distinguishes itself by providing auto-generation of client libraries from API definitions. They all support using **Markdown** to create docs pages.

There are many other features offered by these products, including analytics, AI integrations, collaboration support, automated deployment, and more. A full features comparison is out of the scope of this article, but you can explore the pricing and features for each yourself:
- [GitBook pricing page](https://www.gitbook.com/pricing)
- [ReadMe pricing page](https://readme.com/pricing)
- [Mintlify pricing page](https://mintlify.com/pricing)
- [Fern pricing page](https://buildwithfern.com/pricing)

***

### Requirements for all four test drives
 - Download and use my sample OAD file, [tasksapi.yml](https://github.com/minaelee/tasksapi/blob/main/tasksapi.yml) (right click and *Save link as*).

>Note: In this round, for simplicity's sake, I will only provide instructions for using this file. You can use a different OAD file or the URL to an OAD online if you wish, but you will have to adapt my instructions for yourself. Feel free to message me if you need help!

***

### Mintlify and Fern requirements
While all the products tested in this round embrace the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) paradigm, **Mintlify** and **Fern** particularly were designed around that mindset and accordingly, both require that you have some familiarity with docs-as-code tools (in other words, dev tools) to get started. You will need:
- **Git** installed locally on your computer. See: [Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- A [GitHub](https://github.com) account.
- **Node.js** version 19 or higher installed locally on your computer. Fern currently requires v18 and Mintlify requires v19, so if you only want to test drive Fern and not Mintlify, then v18 is fine. If you don't already have Node.js installed, I recommend using [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) (for macOS) or [nvm-windows](https://github.com/coreybutler/nvm-windows?tab=readme-ov-file#installation--upgrades) (for Windows) to install it. Installing Node.js will give you access to the command line tools [npm](https://docs.npmjs.com/cli/v10/commands/npm) and [npx](https://docs.npmjs.com/cli/v10/commands/npx).
- An **IDE or code editor**. I recommend [Visual Studio Code](https://code.visualstudio.com/).
- Familiarity with using a **CLI (command line interface)** for a shell such as bash or zsh. In macOS, you can use the built-in **Terminal** app, which uses zsh by default. On Windows, I recommend using **Git Bash**, which is installed by default with Git; type *git bash* into the Windows search bar to locate and open it.

***
&nbsp;<br />

## The test drives

### GitBook

{% details %} 
[GitBook](https://gitbook.com) and ReadMe both launched in 2014, which makes them venerable elders in the niche of API documentation tools. GitBook offers two main products: an internal knowledge base and public documentation. We'll explore just the public documentation side.

GitBook allows you to use a custom domain even on the free tier. It also provides a forever-free 'OSS Community' plan for open-source software projects. There's no 'try it' console, but it's said to be on the roadmap. They have [a community forum](https://github.com/GitbookIO/community); of the four products in this round, GitBook is the only one without a Slack workspace or Discord server.

***

#### Instructions
**Step 1.** Create an account at [GitBook's website](https://app.gitbook.com).

**Step 2.** You will be asked to **Create a New Organization**. Choose a name for your organization (the default is fine; you can change the name later). In the **use case** drop down, select **Open Source Docs** or **Product Docs**. 

**Step 3.** At your account's homepage, if you have just created your account, you should see **Untitled** at the top of the main panel, with a **Page** beneath it. If not, click the **+** sign next to the word **Documents** in the left sidebar and choose **New space**. Change the text **Untitled** to **Tasks**.

In the **Page**, click **Import content**. Choose **OpenAPI** from the **Import Your Content** dialog. Select the `tasksapi.yml` file provided in the [General requirements](#general-requirements) section of this article, then click **Start import**.

**Step 4.** Once the import is complete, look for the new **API reference** link on the left. You should now be able to view the imported descriptions as [OpenAPI blocks](https://docs.gitbook.com/content-editor/blocks/openapi).

**Step 5.** To make this API reference available to the public, click the **Share** button at the top right of the page, then from the left panel of the dialog that appears, choose **Publish to the web**. Click the toggle button next to **Publish this space to the web**. You should then see a success message and a link to view your documentation online, plus customization and domain options. Click **Visit site** to see your documentation.

**Step 6 (optional).** To update the documentation you've published, make a change to one of the endpoint descriptions in `tasksapi.yml`. Then go to any one of the API method blocks that were imported; it doesn't matter which one. Click the six-dot icon at the upper left of the block:

![Screenshot of the context menu that appears when you click the six-dot icon described above](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/28i0hb5dfqy9qe0av09z.png)

From the context menu, click **Choose OpenAPI source...** A right sidebar titled **Choose OpenAPI source** will appear. From it, click the three-dots menu next to `tasksapi.yml`, choose **Replace**, then choose your updated file. It should update all the OpenAPI blocks in your documentation that depend on the same source. Confirm that the change you made to the OAD file is reflected in the updated documentation.

> Note: While I was writing this article, I found that GitBook's OpenAPI implementation was frequently changing. Menu options changed, bugs appeared and vanished and reappeared, and so on. It seems like it's under active development, so the instructions given here might become affected by further changes. If you find that my instructions are no longer valid, give me a shout and I'll be happy to update them through the end of 2024. 

[My GitBook-generated docs for comparison](https://minae-test.gitbook.io/tasks/)

#### References
* [GitBook Docs - Create OpenAPI Block Using Your OpenAPI File](https://docs.gitbook.com/content-editor/blocks/openapi#create-openapi-block-using-your-openapi-file)
* [GitBook Community](https://github.com/GitbookIO/community)

***
{% enddetails %}

### ReadMe
{% details %}

Like GitBook, [ReadMe](https://readme.com) has been around since 2014. It was a [2015 YCombinator startup](https://www.ycombinator.com/companies/readme).

ReadMe offers a [free premium plan for open source projects](https://docs.readme.com/main/docs/plans-and-pricing#plans-for-open-source-projects). However, ReadMe does not allow custom domain use on its free plans, either the personal or the open source one.

ReadMe has a 'try it' console called the **API Explorer**. It will not work with the `tasksapi.yml` file I provided for this tutorial, since that OAD does not have any servers defined. If you want to try out their API Explorer, you can download and use [a sample OAD provided by ReadMe](https://public-sample-space.readme.io/openapi/61ef1d793087890045db3e51) (right click and *Save link as*) instead of `tasksapi.yml` in the instructions below. Or you can view their [demo online](https://public-sample-space.readme.io/reference/addpet), which uses the Swagger Petstore demo API and has the API Explorer enabled.

They host a [Slack community](https://readme.com/slack), but it doesn't seem to get much traffic.

***

#### Instructions

**Step 1.** Create an account at [ReadMe's website](https://readme.com).

**Step 2.** You will be prompted to **Create a new project**. Give your project a name. Your subdomain at readme.io will be named automatically from your project name, but you can set it to something else if you wish. You can change both the project name and subdomain later. For **Project type**, click on **Yes, an API**. Click the **Create** button. Note that ReadMe will automatically subscribe each new project to a free trial of the Business plan for 14 days after project creation. After that, it will fall back to the Free plan unless you subscribe to one of the paid plans.

**Step 3.** In the left panel, click **API Reference**. Then in the main panel, click **Add your first API**.

**Step 4.** In the **Describe Your API** dialog, choose **API Import**.

**Step 5.** ReadMe gives you the options of importing via command line, a GitHub repository, a file, or URL. Choose to **upload via file**, then upload the `tasksapi.yml` file you downloaded in the [General Requirements](#general-requirements) section.

**Step 6.** In the **Next Steps** dialog, toggle **Public Visibility** to **ON**, then click **Dismiss**. You should then see a page called **Your API Definitions**, with your OpenAPI document listed.

**Step 7.** At the top left corner, directly below the ReadMe logo, you should see a button with your project name on it. Click on it to be taken to your published documentation. 

>Note: While your project is on the free trial Business plan, your published documentation will show other tabs aside from the API Reference, such as Guides and Recipes. Once the free trial ends, it will only show the API Reference. For more information, see [ReadMe's plan comparison and pricing page](https://readme.com/pricing).

**Step 8 (Optional).** If you wish to update your API definitions, click the **Edit** link next to it. You will be prompted to upload a new OAD file.

[My ReadMe-generated docs for comparison](https://dash.readme.com/project/firstpass/v1.0/reference)

<a name="references-1"></a>
#### References
- [ReadMe Docs - OpenAPI Upload](https://docs.readme.com/main/docs/openapi-upload)
- [ReadMe Docs - OpenAPI Support in ReadMe](https://docs.readme.com/main/docs/openapi)
- [ReadMe Docs - OpenAPI Extensions](https://docs.readme.com/main/docs/openapi-extensions)

***
{% enddetails %}

### Mintlify
{% details %}

Founded in 2021, [Mintlify](https://mintlify.com) is a relative newcomer to the space of documentation SaaS platforms, but it's a heavy hitter. It was a [2022 YCombinator startup](https://www.ycombinator.com/companies/mintlify).

Mintlify has GitHub integration out of the box, a built-in components library, analytics, a strong community with a [Slack workspace](https://mintlify.com/community), a 'try it' console called the API Playground, and more. Using a custom domain is allowed on its free plan. 

***

#### Instructions
**Step 1.** Go to [Mintlify's website](https://mintlify.com) and click **Get Started**.

**Step 2.** Enter your company name and your email. The company name you enter will determine your documentation site's subdomain name, such as yourcompanyname.mintlify.com. Mintlify will send you an email.

**Step 3.** Open the email from Mintlify and click the **Continue** button. 

**Step 4.** You will be prompted to **sign in with GitHub**. Click to sign in, then **Authorize mintlify** to access your GitHub account.

**Step 5.** Once Mintlify has been authorized, click **Create Repository**. 

**Step 6.** You will be shown two CLI commands, one starting with `git clone` and another starting with `git add`. Open your CLI  and navigate to the folder where you wish to keep your Mintlify docs. Copy only the first command, then paste it into your CLI. This will clone a folder named `docs` at the location where you ran the command. You do not need to copy and paste the second command at this time. Click **Mark Completed**.

**Step 7.** You should now see your Mintlify dashboard. Click the link to **(1) Enable automatic updates**, then click **Install and authorize**. This will install Mintlify's GitHub app for updating your documentation.

**Step 8.** In your dashboard, you should see a link that looks like YOUR_COMPANY_NAME.mintlify.app. For example, I used **docstest** for my company name when I initially signed up, so I see a link to **docstest.mintlify.app**. Click on that link to see a starter documentation hub. Click the **API Reference** tab and you should see a set of **Endpoint Examples** using **plant**/**plants**. In the next steps, you will next replace these examples with the examples from the `tasksapi.yml` file.

>Note: Since the `tasksapi.yml` file does not include servers for testing your API, if you want to try out Mintlify's API Playground (their 'try it' console for testing endpoints), you should do it now before going on to Step 9. Or you can simply view their [Mint Starter Kit demo online](https://starter.mintlify.com/api-reference/endpoint/get).

**Step 9.** In the `docs` folder that you cloned locally on your computer in Step 6, locate the `api-reference` folder. Copy the OAD file I provided in the [General Requirements section](#general-requirements) to this `api-reference` folder.

**Step 10.** In your CLI, from the `docs` folder, run the following command:

```bash
npx @mintlify/scraping@latest  --outDir api-reference openapi-file api-reference/tasksapi.yml
```

**Step 11.**
- If the previous command ran correctly, you should see an output in your CLI that shows you a suggested navigation.

**Step 12.** Open the file named `mint.json` in your `docs` folder. Scroll down to near the very bottom and locate the part that looks like this:

```json
    {
      "group": "Endpoint Examples",
      "pages": [
        "api-reference/endpoint/get",
        "api-reference/endpoint/create",
        "api-reference/endpoint/delete"
      ]
    }

```

Delete that part and replace it with the following:

```json
    {
      "group": "task",
      "pages": [
        "api-reference/task/post-task",
        "api-reference/taskget-task",
        "api-reference/task/delete-task"
      ]
    },
    {
      "group": "tasks",
      "pages": [
        "api-reference/tasks/get-tasks",
        "api-reference/tasks/delete-tasks"
      ]
    }
```

Save the `mint.json` file.

**Step 13.** Run the following command in your CLI from the `docs` folder:

```bash
git add . && git commit -m "replace API descriptions" && git push
```

**Step 14.** In the Mintlify dashboard page in your browser, you should now see that your documentation site is updating. Wait for it to finish, then refresh your docs page (the one located at YOUR_COMPANY_NAME.mintlify.app). You're done!

[My Mintlify-generated docs for comparison](https://docstest.mintlify.app/api-reference/task/post-task)

#### References
- [Mintlify Docs - Quickstart](https://mintlify.com/docs/quickstart)
- [Mintlify Docs - OpenAPI Setup](https://mintlify.com/docs/api-playground/openapi/setup)
- [Mintlify on GitHub](https://github.com/mintlify)

***
{% enddetails %}

### Fern
{% details %}
Founded in 2022, [Fern](https://buildwithfern.com) is the baby of the bunch, but a promising one. Like ReadMe and Mintlify, Fern is a [2023 YCombinator startup](https://www.ycombinator.com/companies/fern).

Fern offers two major features: API documentation generation and hosting, along with auto-generated client-side libraries for SDKs. They host a [Discord community](https://discord.com/invite/JkkXumPzcG) where its two founders are active and responsive. 

They do not have an API 'try it' console at this time, and a custom domain is not available on their free plan.

>Disclosure: In the course of writing this article, I noticed issues with their [Docs Quickstart](https://docs.buildwithfern.com/generate-docs) and submitted  [a pull request](https://github.com/fern-api/fern/pull/2567) to fix them in GitHub. Aside from this, I had no affiliation with Fern while researching or writing this article. 

***

#### Instructions
**Step 1.** Make sure you are logged into GitHub, then go to the [Fern Docs Starter repository](https://github.com/fern-api/docs-starter).

**Step 2.** Click the **Use this template** button in the upper right area of the page. This will prompt you to create a new repository based on the Fern Docs Starter template. Name the repository as you like, such as **ferndocs**.

**Step 3.** Click the blue **Code** button, then copy the web URL to your repository that begins with *https://github.com*. 

**Step 4.** In your CLI, navigate to the folder in which you would like to create the local copy of your Fern documentation repository. From there, enter the command `git clone` followed by the web URL you copied in the previous step:

```bash
git clone https://github.com/YOUR_GITHUB_ACCOUNT_NAME/YOUR_REPOSITORY_NAME.git
```

When finished, this operation will create a folder with the same name as your repository, such as `ferndocs`. Inside that folder, you will find a folder named `fern`. All the following folders and files mentioned in the next steps will be located inside that `fern` folder. 

**Step 5.** In the `fern.config.json` file, replace the placeholder organization name with your organization name, or your own name for testing purposes. Do not change the version number or anything else.

**Step 6.** In the `docs.yml` file, update the docs URL to reflect the subdomain of docs.buildwithfern.com where you wish to publish your documentation. For example:

```yaml
instances:
  - url: your-organization.docs.buildwithfern.com
```

**Step 7.** Install the Fern CLI globally by running:

```bash
npm install -g fern-api
```

As this is a global command, you can run it from any location. The CLI commands in the following steps must be run from within your repository.

**Step 8.** Delete the `definition` folder.

**Step 9.** Place the `tasksapi.yml` in the `fern` folder

**Step 10.** Run:

```bash
fern init --openapi tasksapi.yml
```

You should now see a folder named `openapi`, and inside it will be a copy of the `tasksapi.yaml` file. This is the file that will be used to generate your documentation. 

**Step 11.** Run:
```
fern generate —docs
```
You should see a link to your published documentation, hosted by Fern.

**Step 12 (optional).** To update your documentation, edit `openapi/tasksapi.yaml` then run `fern generate —docs` again.

[My Fern-generated docs for comparison](https://ferntest4.docs.buildwithfern.com/)

#### References
- [Fern Docs - Docs Quickstart](https://docs.buildwithfern.com/generate-docs)
- [Fern on GitHub](https://github.com/fern-api/fern)

{% enddetails %}


***

## Coming up
Part 3: Stoplight, Swagger, Postman