How to generate documentation for your REST API for free

This tutorial will show you how to generate documentation for your REST API from an OpenAPI or Swagger file using a free online tool.

This will be useful if you:

• You are designing a new API and want to share a draft with a teammate to get quick feedback.
• You want to quickly share API documentation outside of your organization with a partner or customer, but aren't ready to publish an entire documentation site yet.
• You want to share an API with a non-engineering stakeholder, such as a product manager, and so don't want to share the plain OpenAPI or Swagger file.

This tutorial will use the Criteria Playground to create a permalink to API documentation and. Creating permalinks is free and you don't need to create an account.

Criteria Playground can be accessed at https://criteria.sh/play.

Step 1: Open your OpenAPI or Swagger file

Criteria Playground can load OpenAPI files from a number of sources. This tutorial will assume that your OpenAPI file is saved to your Desktop.

Open the OpenAPI file:

1. Choose File > Open File.
2. In the dialog, select the OpenAPI file and click Open.
3. If your browser requests permission to edit the document, allow editing.

The file will appear in Criteria Playground in three areas:

• The navigator, for managing files in the project.
• The editor pane, for editing the text content of a file.
• The preview pane, for previewing a file, depending on the file's type.

When the OpenAPI file is selected the preview pane will show the API documentation in a condensed, single-page format.

If you edit the file in the playground, changes will be saved to your computer. This allows you to use Criteria Playground as an IDE.

Step 2: Preview docs

In addition to using the preview pane, you can generate a documentation portal for your API. The documentation automatically includes a sidebar for navigation and a split view containinig generated request and response examples for each endpoint.

Generate API documentation:

1. Click Preview in the playground header in the top-right corner.

Step 3: Share as a permalink

So far the OpenAPI file is still saved on your computer. You can generate a permalink that will enable anyone with the link to view the API documentation.

Generate and share a permalink:

1. Click Share in the playground header in the top-left corner.
2. Click the link URL that appears next to the Share button to copy it to your clipboard.

The link URL represents a snapshot of your API project. Further edits you make to the API will not be reflected in at the URL, however you can always generate a new link.

The link can be shared with anyone; they don't need to create an account.

Next steps

This tutorial only scratched the surface of what is possible in Criteria Playground.

Here's some suggestions of additional things that you can do:

• Make changes to the API.

  Criteria Playground is a full IDE for designing APIs. Use the inspector to quickly add or modify resources and endpoints without having to edit JSON or YAML by hand.

• Add a spectral.yaml file.

  Detect and fix style issues in real-time as you edit APIs.

• Send requests.

  Use the API Explorer to send requests to a backend directly from the browser.

About Criteria

Criteria is a collaborative platform for the entire API lifecycle, from design, development to publishing.

If you want to publish API documentation to a custom subdomain, get in touch with us.