Forem: minae

Book Synopsis & Review - Docs Like Code

minae — Fri, 31 May 2024 00:36:00 +0000

ABOUT THIS BOOK

This book is meant as a resource for technical writing teams who are using, or are moving toward, a docs-as-code approach. The first edition was published in 2017, and I read the third edition, published in 2022. Anne Gentle (Cisco) and Diane Skwish are co-authors, and Kelly Holcomb (Oracle) is listed as a contributor. Eric Holscher (founder of the ReadTheDocs platform and the WriteTheDocs community & conference) wrote the foreword for this edition.

BOOK CONTENTS

At only 127 numbered pages, this book is slim but densely packed with useful information. There is a lot of technical detail, so I don't consider it suitable for anyone brand new to software documentation. Mainly, if you have never used git (a software version control and collaboration system), the many discussions on git pull requests and git branches and such won't make much sense to you. This book is not intended to teach you these concepts. It does, however, provide a list of resources for learning git, and a glossary of git-related terms and definitions.

Docs Like Code contains four chapters:

Introducing docs as code
Plan for docs as code
Optimize workflows with docs as code systems
Lessons learned with docs as code

The first chapter defines a docs-as-code framework as one where you:

Store the doc source files in a version control system
Build the doc artifacts automatically
Ideally, run automated tests on the docs
Ensure that a trusted set of reviewers meticulously review the docs
Publish the artifacts without much human intervention

The second chapter (Plan for docs as code) includes sections on:

Requirements gathering
Planning for automating, testing, and site hosting
Organizing source files and repositories
API reference documentation
and more

Many topics are covered in these sections, from choosing a markup language (Markdown, AsciiDoc, RST, etc...), to using mermaid diagrams, to determining API complexity, to choosing a static site generator. This book doesn't provide a deep dive into single topic; it provides seasoned advice and enough to get you started.

The requirements gathering section presents a wide variety of useful questions, such as:

Does the source repository need to be private or can it be publicly available?
How do users access the docs, and how often from each platform?
How much [of the budget] should you allocate per author, per deliverable, and for hosting?
Are you relying on an internal team or a third party to have "pager duty" if the docs site goes down?

If you are a team planning to adopt docs-as-code, this section alone is worth the book as a useful checklist for everything you need to consider.

The third chapter (Optimize workflows with docs as code systems) is the thickest of the four. It's also where prior knowledge of how to use git is most necessary, as much of it is concerned with git-based workflows.

Questions considered in this chapter include:

Are the docs in their own repo?
How will you publish?
Will contributors preview docs locally or on a server?
How will you collaborate with others?
How many pull requests and reviews do you expect?

This chapter also includes advice on using a CODEOWNERS file, creating a docs contributors guide, writing a style guide, building locally, automation, review processes, versioning, and more. Many useful docs-as-code tools are recommended, such as the prose linter Vale, broken link checkers, Docker, GitHub Actions, Jekyll, and others.

The final chapter (Lessons learned with docs as code) is the thinnest - only 9 pages, with a few paragraphs devoted to each of these lessons:

Find your community and learn from others
Create a great web experience
Equip your contributors with a style guide
How will you collaborate with others?
Empower your contributors
Write a contributor's guide
Write a reviewer's guide
Build in continuous integration for docs
Teach everyone to respect the docs
Test and measure outcomes
Set up a Git support chat room

What's not in this book

This book does not contain any information about the use of AI in docs-as-code, aside from mentioning the rise of AI/ML in documentation.

There is no index, which I found disappointing. Considering the breadth of topics covered, an index would be quite useful.

Overall

This book is not a tutorial. It will not teach you how to use docs-as-code. However, it's an extremely useful book that covers countless facets about docs-as-code. Pick it up if you're thinking about switching to docs-as-code or if you want to figure out holes in your existing approach that need to be considered.

Learn more about docs-as-code

Docs Like Code (a companion website to the book, with supplementary articles and tutorials)
Write The Docs - Docs As Code
I'd Rather Be Writing - Docs as code
I'd Rather Be Writing - Docs-as-code tools

How to use the multi-blog plugin for Docusaurus

minae — Tue, 20 Feb 2024 22:01:16 +0000

Why I wrote this
What's Docusaurus?
Requirements
Instructions
- Step 1. Create a Docusaurus project.
- Step 2. Open the project in a code editor
- Step 3. Add the second blog's folder and file
- Step 4. Add the multi-blog plugin to docusaurus.config.js
- Step 5. Run the dev server and view your site
- Next steps

Why I wrote this

Recently, I helped someone who had trouble installing the multi-blog plugin for Docusaurus. The instructions on their website are not clear for non-technical users, and she kept getting a 404 Not Found when trying to access the second blog. This post expands on their instructions with more details and screenshots for less technical users.

What's Docusaurus?

Docusaurus is a Jamstack SSG (Static Site Generator) mainly intended for documentation and blog websites. It is a Meta Open Source project. It is configured with a JavaScript file called docusaurus.config.js.

Requirements

Node.js 18 or above installed
- Instructions for installing Node.js using a version manager
Some familiarity with a CLI (Command Line Interface)
An IDE or code editor
- I recommend Visual Studio Code

Instructions

Step 1: Create a Docusaurus project

If you don't already have a Docusaurus project, create one now using the npx CLI command:



npx create-docusaurus@latest twoblogs classic

npx is a CLI tool bundled with Node.js that lets you access code packages hosted by the organization called NPM (Node Package Manager). In this case, npx accesses and runs the create-docusaurus package with the classic template. If the command succeeds, it creates a folder on your computer named twoblogs/.

Step 2: Open the project in a code editor

Open the newly created project folder in your code editor. If you use VS Code, the following command (run from the same location where you ran the previous command) will open the twoblogs/ folder in VS Code:



code twoblogs

In VS Code, the newly created project's structure looks like this:

Step 3: Add the second blog's folder and file

In the twoblogs/ folder, create a new folder named blog2/. In it, create a new file named index.md. Write the text # Hello World in index.md:

Step 4: Add the multi-blog plugin to docusaurus.config.js

Open the file docusaurus.config.js. The next step is to add a plugins object as a property of the config object defined in this file.

Scroll down until you see the themeConfig object:

Above it, add the following code:



  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        id: 'blog2',
        routeBasePath: 'blog2',
        path: './blog2',
      },
    ],
  ],

The file should now look like this:

Step 5: Run the dev server and view your site

Open a CLI shell to the twoblogs/ folder. In VS Code, you can do this by going to the Terminal menu across the top and choosing New Terminal. (Or use a keyboard shortcut: Ctrl+j for Windows, or Cmd+j for macOS.)

Enter the following command in your CLI shell:



npm run start

Expected output:

Ignore the yellow warning about git. For a production site, you would want to add a git repository as the warning indicates, but it is not necessary for this quick tutorial. Your only concern for now is to make sure you see the final line that says "compiled successfully".

Your default browser should open automatically to http://localhost:3000/. Add blog2 to the end of the URL and you should see your second blog's index.md page displayed:

That's it! If you can see your Hello World message, your multi-blog plugin is working.

What's next?

Learn how to deploy your site
Learn more about Docusaurus
Learn more about Docusaurus blogs
Join the Docusaurus community on Discord

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

minae — Wed, 07 Feb 2024 08:21:58 +0000

We're in the home stretch!

This is Part 3 of a series. To understand the scope and purpose of this series, I recommend that you check out at least the first article's Introduction before you begin this article.

Preliminaries
- What are we test driving ❓
- What should I know about them first ❓
The test drives
- Requirements for all test drives
- Swagger
  - SwaggerUI
    - Additional requirements for SwaggerUI
    - Instructions
  - SwaggerHub
    - Instructions
- Stoplight
  - Additional requirements for Stoplight
  - Instructions
- Postman
  - Instructions
Conclusion

Preliminaries

What are we test driving ❓

We're finishing up our test drives of ten OpenAPI documentation generators by taking Swagger (started in 2011), Postman (2014), and Stoplight (2015) for a spin.

Taking the 'learn-by-doing' approach, we'll give ourselves a quick-and-dirty introduction to each of these products by taking an OpenAPI Description file (a JSON or YAML/YML file formatted using the OpenAPI Specification) and taking the most direct route to generate API reference documentation with it.

What should I know about them first ❓

Like the four OpenAPI documentation generators in Part 2, these are all Software as a Service (SaaS) products, meaning they are subscription-based cloud services. Each has a free tier that allows you to publish public-facing documentation, with limitations.

The three in this round offer documentation generation as a part of a suite of tools for the entire API lifecycle, from design to testing to deployment and more. If you choose to use one of these for documenting your APIs, then you might want to adopt their entire suite. However, since documentation generation is only a small part of each of these companies' products, you might find that there is less focus on that aspect. In my experience, I found this to especially be true for Postman. Thus, some might choose to use a specialized tool for documentation only, such as those we saw in Parts 1 & 2 of this series, and use Swagger, Stoplight, or Postman for the other aspects of the API lifecycle.

Swagger has a special history with the OpenAPI Specification (OAS) because, well, they originated it. It was called the Swagger specification until they handed it over to the Linux Foundation, who renamed it and created the OpenAPI Initiative to maintain it.

Stoplight (a.k.a. Stoplight Platform) also maintains the free, open-source Stoplight Elements documentation generator that I test-drove in Part 1.

Both Swagger and Stoplight belong to a parent company called SmartBear. Swagger was acquired by SmartBear in 2015, and Stoplight only recently in 2023. Since their products have a ton of overlap, Stoplight's acquisition might signal changes to come to it, Swagger, or both.

Postman and SmartBear are both official members of the OpenAPI Initiative. Stoplight's CTO and Postman's OAS Lead are both active maintainers of the OpenAPI Initiative.

The test drives

Requirements for all test drives

An OAD (OpenAPI Description) file, meaning a JSON or YAML/YML file that describes an API using the OpenAPI Specification format. Use your own or download my sample file, tasksapi.yml (right-click the link and choose Save link as).

Swagger

Swagger offers two ways to generate publicly accessible documentation from OpenAPI. I'll test drive both approaches.

1) You can use SwaggerUI to generate documentation that you can host wherever you wish, just like the three documentation generators I test-drove in Part 1. Instructions for using SwaggerUI.

2) You can use their SaaS product called SwaggerHub. Instructions for using SwaggerHub.

SwaggerUI

Additional requirements for SwaggerUI

A code editor, such as Visual Studio Code
A way to run a development HTTP server on your local computer
Familiarity with using a CLI shell such as bash or zsh (I recommend Git Bash on Windows and the Terminal app on macOS)

Instructions

Step 1. From this page, download and extract their standalone zip or tarball of HTML/CSS/JS files.

If you prefer to use NPM or Docker to install the necessary files, scroll up on that same page for instructions.

Step 2. Use your code editor to open the file named swagger-initializer.js in the extracted dist/ folder. In it, provide the path or URL to your OpenAPI file. For example, if you are using my tasksapi.yml file, copy that file to the dist/ folder, then use this path for the url property in swagger-initializer.js:

  window.ui = SwaggerUIBundle({
    url: "./tasksapi.yml",

Step 3. Run your local development server from the dist/ folder. If you are using Visual Studio Code with the Live Server extension, right-click the index.html file in the dist/ folder and choose Open with Live Server. Your generated documentation should display in your default browser, as shown in this screenshot:

Step 4 (Optional). For deployment, see the deployment section from Part 1 of this article series. Use the same instructions, but upload the dist/ folder to Netlify.

SwaggerHub

Instructions

Step 1. Create an account at SwaggerHub.

Step 2. From the dashboard, click Import API.

Step 3. In the dialog that appears, enter the path/URL to your OpenAPI Description file. Set its visibility to Public. Click Import or Upload File. (The option will vary depending on whether you chose a local file or a URL.)

Step 4. SwaggerHub will check your OAD to make sure that it is valid according to the OpenAPI Specification. You should see a message that says Success. If there are any errors, fix them and try again. You will have a chance to set the name and version. You can leave these at their defaults for this test drive. Click Import Definition.

Step 5. You should see a page with your OAD file contents along with generated documentation to the right. You can share the URL of this page with others. If you need to update your OAD, you can do so from this page. You can also share a page of just the documentation without the OAD. To do this, look for a button with a file icon on the upper right that, when hovered over, shows the text View Documentation:

Click that button to see your publicly viewable online documentation without the OAD shown next to it. You can share this URL with others as well.

View the example online.

Stoplight

Additional requirements for Stoplight

A GitHub account

Instructions

Step 1. Create a new account at Stoplight.io. When directed, choose GitHub to connect and authorize Stoplight to use GitHub.

Step 2. From the left sidebar, click Start New Project.

Step 3. Click the link to Import OpenAPI File:

Step 4. In the center panel, enter a name for your project (such as "Tasks API"), then click Create Project & Import File:

Step 5. Once the project is created, click the button to import an existing OpenAPI file:

Step 6. When the OpenAPI file import is completed, you should see the filename on the left side, as shown below. Click the green Publish button above it.

When the project is published, you'll see a dialog titled Share Project: Tasks API. Hit the X on its upper right to exit this dialog.

Step 7. Click the Go to Docs button on the upper left.

You should now see the publicly accessible documentation generated by Stoplight from your OAD, as in the example shown below. You can share the URL of this page with others.

Like SwaggerHub, Stoplight lets you edit your OAD from its web portal. Return to the previous page you saw in Step 6, then click the OpenAPI filename (such as tasksapi.yml). You will then see options to edit any part of the OAD, as shown below:

View the example online.

Postman

Instructions

Step 1. Create an account at Postman.com.

Step 2. From your dashboard, click the link for API documentation:

Step 3. In the next screen, click the APIs button on the left, then click the Import button:

Step 4. Select your OAD file or enter a URL to an online OAD. You will be asked to choose how to import your API. Choose OpenAPI with a Postman Collection:

Then click the Import button. You will see your API's title (as defined in the OAD file) appear in your Postman Workspace:

Expand it to see testing and editing options. Like SwaggerHub and Stoplight, Postman allows you to edit/update your OAD from their web editor:

Step 5. Click the Collections button on the left to see a collection created from your OAD. With it selected, click the link to View complete documentation:

Step 6. In the next page, click the Publish button on the upper right:

Step 7. You will be presented with a page of customization options. At the bottom of the page, click Publish.

Step 8. You will be shown a link to the published documentation. Click it to view your publicly viewable docs generated from OpenAPI. You can share this URL with others.

Example:

View the example online.

Conclusion

Let's recap.

Part 1: Redoc, Spotlight Elements, and Rapidoc are free, open-source products that use custom HTML elements/Web Components to generate documentation webpages from OpenAPI Description files, which you are then responsible for serving online so that others can view it.

Part 2: GitBook, ReadMe, Mintlify, and Fern are Software as a Service (SaaS) products that focus on software documentation. That means not only API reference documentation but other documentation as well, such as tutorials and guides. They can all generate API references from OpenAPI out of the box, and they all provide non-expiring free tiers with publicly viewable documentation. None of these give you the option to generate documentation on your own computer for self-hosting.

Part 3: Swagger, Stoplight, and Postman are full SaaS suites for the entire API lifecycle, from design to development to testing to documentation and so on. They can all generate API documentation from OpenAPI out of the box, and they all provide non-expiring free tiers with publicly viewable documentation. Swagger's free SwaggerUI product can be used to generate local documentation files that you can self-host, but its SaaS product, SwaggerHub, does not generate local documentation, and neither do Stoplight nor Postman.

And we're done! -cue brakes-squealing noises-

Thanks for coming along with me in test-driving these ten OpenAPI documentation generators. I learned a lot about what's available out there to address this need, and I hope you did as well.

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

minae — Mon, 22 Jan 2024 05:37:44 +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 in this series, check out at least its Introduction to get up to speed. Pun intended.

Preliminaries
- What are we test driving ❓
- What should I know about them first ❓
- Requirements for all four test drives
- Mintlify and Fern requirements
The test drives
- GitBook
- ReadMe
- Mintlify
- Fern
Coming up

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

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

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.

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

Fern

Founded in 2022, Fern is the baby of the bunch, but a promising one. Like ReadMe and Mintlify, Fern is a 2023 YCombinator startup.

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

Coming up

Part 3: Stoplight, Swagger, Postman

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

minae — Tue, 09 Jan 2024 06:12:11 +0000

Introduction
- Who might benefit from this article series ❓
- What do I mean by 'test driving' ❓
- What documentation generators will this article series cover ❓
- Why these ten ❓
Test Drives
- What to know before we ride
- Requirements
- Part 1: Generate docs from OpenAPI
- How to open a development HTTP server
- Part 2: Make your docs viewable online
- Final Notes
  - Details & comparison
  - Where to find live demos
  - Usage notes
  - Redoc vs Redocly and Stoplight Elements vs Stoplight

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

RAPIDOC SCREENSHOT

STOPLIGHT ELEMENTS SCREENSHOT

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

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!

Forem: minae

Book Synopsis & Review - Docs Like Code

ABOUT THIS BOOK

BOOK CONTENTS

What's not in this book

Overall

Learn more about docs-as-code

How to use the multi-blog plugin for Docusaurus

Contents

Why I wrote this

What's Docusaurus?

Requirements

Instructions

Step 1: Create a Docusaurus project

Step 2: Open the project in a code editor

Step 3: Add the second blog's folder and file

Step 4: Add the multi-blog plugin to docusaurus.config.js

Step 5: Run the dev server and view your site

What's next?

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

Contents

Preliminaries

What are we test driving ❓

What should I know about them first ❓

The test drives

Requirements for all test drives

Swagger

SwaggerUI

Additional requirements for SwaggerUI

Instructions

SwaggerHub

Instructions

Stoplight

Additional requirements for Stoplight

Instructions

Postman

Instructions

Conclusion

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

Contents

Preliminaries

What are we test driving ❓

What should I know about them first ❓

Requirements for all four test drives

Mintlify and Fern requirements

The test drives

GitBook

Instructions

References

ReadMe

Instructions

References

Mintlify

Instructions

References

Fern

Instructions

References

Coming up

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

Contents

Introduction

Who might benefit from this article series ❓

What do I mean by 'test driving' ❓

What documentation generators will this article series cover ❓

Why these ten ❓

Test Drives

What to know before we ride

Requirements

Part 1: Generate docs from OpenAPI

How to open a development HTTP server

Part 2: Make your docs viewable online

Final Notes

Details & comparison

Where to find live demos

Usage notes

Redoc vs Redocly and Stoplight Elements vs Stoplight