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

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.

Instructions

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 tasksapi.yml file provided in the 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.

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:

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

References

• GitBook Docs - Create OpenAPI Block Using Your OpenAPI File
• GitBook Community

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

They host a Slack community, but it doesn't seem to get much traffic.

Instructions

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 tasksapi.yml file you downloaded in the 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.

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

References

• ReadMe Docs - OpenAPI Upload
• ReadMe Docs - OpenAPI Support in ReadMe
• ReadMe Docs - OpenAPI Extensions

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.

Instructions

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

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 to this api-reference folder.

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

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:

    {
      "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:

    {
      "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:

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

References

• Mintlify Docs - Quickstart
• Mintlify Docs - OpenAPI Setup
• Mintlify on GitHub

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.

Instructions

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

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:

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

Step 7. Install the Fern CLI globally by running:

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:

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

References

• Fern Docs - Docs Quickstart
• Fern on GitHub