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 in this series, check out at least its Introduction to get up to speed. Pun intended.
Contents
Preliminaries
What are we test driving ❓
This round, we're taking GitBook (started in 2014), ReadMe (2014), Mintlify (2021), and Fern (2022) for a spin.
What should I know about them first ❓
The three options that I test drove in the previous round (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:
Requirements for all four test drives
- Download and use my sample OAD file, 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 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
- A GitHub 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 (for macOS) or nvm-windows (for Windows) to install it. Installing Node.js will give you access to the command line tools npm and npx.
- An IDE or code editor. I recommend Visual Studio Code.
- 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.
The test drives
GitBook
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; of the four products in this round, GitBook is the only one without a Slack workspace or Discord server. Step 1. Create an account at GitBook's website. 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 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. 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 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 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
GitBook 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.
Instructions
tasksapi.yml file provided in the General requirements section of this article, then click Start import.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:
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.
References
ReadMe
Like GitBook, ReadMe has been around since 2014. It was a 2015 YCombinator startup. ReadMe offers a free premium plan 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 They host a Slack community, but it doesn't seem to get much traffic. Step 1. Create an account at ReadMe's website. 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 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. 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
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 (right click and Save link as) instead of tasksapi.yml in the instructions below. Or you can view their demo online, which uses the Swagger Petstore demo API and has the API Explorer enabled.
Instructions
tasksapi.yml file you downloaded in the General Requirements section.
References
Mintlify
Founded in 2021, Mintlify is a relative newcomer to the space of documentation SaaS platforms, but it's a heavy hitter. It was a 2022 YCombinator startup. Mintlify has GitHub integration out of the box, a built-in components library, analytics, a strong community with a Slack workspace, a 'try it' console called the API Playground, and more. Using a custom domain is allowed on its free plan. Step 1. Go to Mintlify's website 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 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 Note: Since the Step 9. In the Step 10. In your CLI, from the Step 11. Step 12. Open the file named Delete that part and replace it with the following: Save the Step 13. Run the following command in your CLI from the 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
Instructions
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.tasksapi.yml file.
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.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 to this api-reference folder.docs folder, run the following command:
npx @mintlify/scraping@latest --outDir api-reference openapi-file api-reference/tasksapi.yml
mint.json in your docs folder. Scroll down to near the very bottom and locate the part that looks like this:
{
"group": "Endpoint Examples",
"pages": [
"api-reference/endpoint/get",
"api-reference/endpoint/create",
"api-reference/endpoint/delete"
]
}
{
"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"
]
}
mint.json file.docs folder:
git add . && git commit -m "replace API descriptions" && git push
References
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 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 and submitted a pull request to fix them in GitHub. Aside from this, I had no affiliation with Fern while researching or writing this article. Step 1. Make sure you are logged into GitHub, then go to the Fern Docs Starter repository. 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 When finished, this operation will create a folder with the same name as your repository, such as Step 5. In the Step 6. In the Step 7. Install the Fern CLI globally by running: 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 Step 9. Place the Step 10. Run: You should now see a folder named Step 11. Run: You should see a link to your published documentation, hosted by Fern. Step 12 (optional). To update your documentation, edit My Fern-generated docs for comparison
Founded in 2022, Fern is the baby of the bunch, but a promising one. Like ReadMe and Mintlify, Fern is a 2023 YCombinator startup.
Instructions
git clone followed by the web URL you copied in the previous step:
git clone https://github.com/YOUR_GITHUB_ACCOUNT_NAME/YOUR_REPOSITORY_NAME.git
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. 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.docs.yml file, update the docs URL to reflect the subdomain of docs.buildwithfern.com where you wish to publish your documentation. For example:
instances:
- url: your-organization.docs.buildwithfern.com
npm install -g fern-api
definition folder.tasksapi.yml in the fern folder
fern init --openapi tasksapi.yml
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.
fern generate —docs
openapi/tasksapi.yaml then run fern generate —docs again.
References
Coming up
Part 3: Stoplight, Swagger, Postman
Top comments (0)