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.

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.

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.