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.
Contents
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. Step 1. From this page, download and extract their standalone zip or tarball of HTML/CSS/JS files. Step 2. Use your code editor to open the file named Step 3. Run your local development server from the Step 4 (Optional). For deployment, see the deployment section from Part 1 of this article series. Use the same instructions, but upload the 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.
SwaggerUI
Additional requirements for SwaggerUI
Instructions
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",
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:
dist/ folder to Netlify.
SwaggerHub
Instructions
Stoplight
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:
Additional requirements for Stoplight
Instructions
Postman
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:
Instructions
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.
Top comments (0)