Test Driving OpenAPI Documentation Generators (2024) - Part 3 of 3
Tags: openapi, saas, documentation, tooling
Published: 2024-02-07 08:21:58

---
title: Test Driving OpenAPI Documentation Generators (2024) - Part 3 of 3
published: true
series: Test Driving OpenAPI Documentation Generators
description: Quickstart tutorials for and discussion about generating API reference documentation from OpenAPI using Swagger (SwaggerUI and SwaggerHub), Stoplight, and Postman
tags: openapi, saas, documentation, tooling
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ezebefpk5p8o7hlxdqj5.jpg
# published_at: 2024-01-22 06:12 +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](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7#introduction) before you begin this article.

***

## 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)
- [The test drives](#the-test-drives)
   * [Requirements for all test drives](#requirements-for-all-test-drives)
   * [Swagger](#swagger)
      + [SwaggerUI](#swaggerui)
         - [Additional requirements for SwaggerUI](#additional-requirements-for-swaggerui)
         - [Instructions](#instructions)
      + [SwaggerHub](#swaggerhub)
         - [Instructions](#instructions-1)
   * [Stoplight](#stoplight)
      + [Additional requirements for Stoplight](#additional-requirements-for-stoplight)
      + [Instructions](#instructions-2)
   * [Postman](#postman)
      + [Instructions](#instructions-3)
- [Conclusion](#conclusion)

***

## Preliminaries
&nbsp;<br />

### What are we test driving :question:
We're finishing up our test drives of ten OpenAPI documentation generators by taking [Swagger](https://swagger.io/) (started in 2011), [Postman](https://www.postman.com/) (2014), and [Stoplight](https://stoplight.io/) (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](https://www.openapis.org/what-is-openapi)) and taking the most direct route to generate API reference documentation with it.

***
&nbsp;<br />

### What should I know about them first :question:

Like the four OpenAPI documentation generators in [Part 2](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-2-of-3-id2#what-are-we-test-driving-question), 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](https://www.openapis.org/) 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](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7).

Both Swagger and Stoplight belong to a parent company called [SmartBear](https://smartbear.com/). 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](https://www.openapis.org/membership/members). **Stoplight**'s CTO and **Postman**'s OAS Lead are both [active maintainers](https://github.com/OAI/OpenAPI-Specification/blob/main/MAINTAINERS.md) of the OpenAPI Initiative. 

***
&nbsp;<br />

## 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, <a href="https://github.com/minaelee/tasksapi/blob/main/tasksapi.yml" target="_blank">tasksapi.yml</a> (right-click the link and choose _Save link as_). 

### Swagger

{% details %} 

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

1) You can use **[SwaggerUI](https://swagger.io/tools/swagger-ui/)** to generate documentation that you can host wherever you wish, just like the three documentation generators I test-drove in [Part 1](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7). [Instructions for using SwaggerUI.](#swaggerui)

2) You can use their SaaS product called **[SwaggerHub](https://swagger.io/tools/swaggerhub)**. [Instructions for using SwaggerHub.](#swaggerhub)


&nbsp;<br />

#### SwaggerUI

##### Additional requirements for SwaggerUI

- A code editor, such as [Visual Studio Code](https://code.visualstudio.com/) 
- A way to [run a development HTTP server](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7#how-to-open-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](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md#plain-old-htmlcssjs-standalone).
- 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`:

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

![Screenshot of documentation generated from OpenAPI using SwaggerUI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5qu13row5sq25gd0hntz.png)

**Step 4 (Optional).** For deployment, see [the deployment section from Part 1 of this article series](https://dev.to/dreamlogic/test-driving-openapi-documentation-generators-2024-part-1-of-3-9a7#part-2-make-your-docs-viewable-online). Use the same instructions, but upload the `dist/` folder to Netlify.

&nbsp;<br />

#### SwaggerHub

##### Instructions

**Step 1.** Create an account at [SwaggerHub](https://swagger.io/tools/swaggerhub/).

**Step 2.** From the dashboard, click **Import API**.
![Screenshot of Import API popup dialog in SwaggerHub](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ndasoo7s3265aii5frrw.png)

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

![Screenshot of View Documentation button](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e907d1g88brocsx6vo7v.png)

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.](https://app.swaggerhub.com/apis-docs/MINAELEE/to-do_list/1.0.0)

***
{% enddetails %} 

### Stoplight
{% details %} 

#### Additional requirements for Stoplight
- A [GitHub](https://github.com/) account

#### Instructions
**Step 1.** Create a new account at [Stoplight.io](https://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**:

![Screenshot of link to Import OpenAPI File](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5ne7djlflbtbvvlm7wml.png)

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

![Screenshot of panel to enter project name and create project/import file](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0ion3h5me6z6j32lrusj.png)

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

![Screenshot of OpenAPI button to import an existing OpenAPI file](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7gz5txgwsw13ib5t61bl.png)

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

![Screenshot showing completed OpenAPI file upload and the Publish button above it](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/p4hwtzrrpmmz59e908ep.png)

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.

![Screenshot of Go to Docs button](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6r4d8tg6qwiob4z9bw18.png)

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.

![Screenshot of documentation generated by Stoplight from OAD](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qu95r78f6t7fphi10aa6.png)

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:

![Screenshot of OAD web editor built into Stoplight portal](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8ypyz72qjzcfpwhv3un3.png)

[View the example online.](https://minae.stoplight.io/docs/tasks-api/branches/main/6qoq1etkin55k-tasks-tracking-app)

***
{% enddetails %}

### Postman
{% details %} 
#### Instructions

**Step 1.** Create an account at [Postman.com](https://postman.com).

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

![Screenshot of API documentation button](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jk1iswp9sd7kpwu1k12j.png)

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

![Screenshot of APIs and Import buttons](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2z0fk8oqv17ozoe0paoa.png)

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

![Screenshot of dialog that requests you to choose how to import your API](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5ppfotiy3wmeivvf2fwk.png)

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

![Screenshot of API title in Postman](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/c078na4lmh6chmzicqzc.png)

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

![Screenshot of API Definition editor in Postman](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kwkxyfugz525x5hj1ea4.png)

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

![Screenshot of link to view complete documentation for a collection](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6uc3dxop6rrwiap7cr4s.png)

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

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/13l4otr60wx5oud5yu36.png)

**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:
![Screenshot of example documentation generated by Postman from OpenAPI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2n8g8uydlhel6osg7e3y.png)

[View the example online.](https://documenter.getpostman.com/view/4965758/2s9Yyy7yEw)

{% enddetails %}

***
&nbsp;<br />

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