Documenting your API

Documentation is an important part of any collection or API. Good documentation helps the people who use your collection to understand what it does and how each request works. And comprehensive API documentation lets your consumers know what endpoints are available and how to successfully interact with them.

Once you've generated documentation for your collection or API, users can view the documentation in Postman. By default your documentation is private, so only people you share a collection or API with will be able to see it. If you're creating a public API, you can publish your documentation to make it publicly available to anyone with a web browser.

Contents

• Documenting a collection
• Generating API documentation
  • Viewing schema documentation
  • Creating new documentation for an API
  • Adding existing documentation to an API
  • Editing API documentation
  • Removing API documentation
• Associating environments with documentation
• Versioning your docs
• Next steps

Documenting a collection

Postman automatically generates basic documentation for any collection you create. View the documentation to see details for all of the requests in your collection, along with sample code in various client languages. Request details include the method, authorization type, URL, headers, request and response structures, and examples. In addition, the documentation displays all key-value pairs for request parameters, headers, and bodies.

To make your documentation even more valuable to users, add descriptions to the items in your collection. Any descriptions you add are automatically included in the documentation for your collection.

1. Select Collections in the sidebar, and then select a collection, folder, or request.
2. Select Documentation in the context bar.
3. Select the edit icon next to the description.
4. Compose your new content, and then select Save. To learn more about using Postman's built-in editing tools, see Authoring your docs.

You can also edit descriptions when viewing the complete documentation for a collection. Select View complete collection documentation at the bottom of the Documentation pane, and then edit the descriptions as usual.

Generating API documentation

The Documentation tab in the API Builder provides one place to view, create, and manage all of your API's documentation. Postman automatically generates API docs for any OpenAPI 3.0 schema defined in the API Builder. You can also add detailed documentation to any API by generating a collection from the API or by linking to an existing collection.

A collection can be linked to only one version of an API. If you create a new version of your API, you'll also need to generate a new collection to hold that version's documentation. To learn more, see Versioning your docs.

Viewing schema documentation

If you are designing an API based on the OpenAPI 3.0 specification, Postman automatically creates documentation based on your schema definition.

The API documentation includes complete API, path, and operation information, such as authentication methods, parameters, request bodies, response bodies and headers, and examples. The documentation also includes schema information for various data models, such as required attributes, default, minimum, and maximum values, and other constraints.

To view the documentation for an OpenAPI 3.0 schema:

1. Select APIs in the left sidebar, and then select an API and a version.
2. Select the Documentation tab.
3. In the left pane, select an item under Schema Documentation to view a specific path or request.

Postman alerts you if your API schema contains unsaved changes or errors. To update the API documentation with the latest schema changes, select the Definition tab and save your schema.

Creating new documentation for an API

To generate a new collection for API documentation:

1. Select APIs in the left sidebar, and then select an API and a version.
2. Select the Overview tab.
3. Select the + next to Documentation, and then select Create new documentation.
4. Enter a name for the new collection. (Make it something you'll easily associate with this version of your API.)
5. (Optional) Select Show advanced settings and change any settings as needed. See the description for each setting to learn more.
6. Select Create Documentation. The new API documentation is displayed in the Documentation tab.

You can generate additional documentation collections from the Documentation tab. In the left pane, select the + next to Collection Documentation, and then select Create Documentation.

Adding existing documentation to an API

To use an existing collection for API documentation:

1. Select APIs in the left sidebar, and then select an API and a version.
2. Select the Overview tab.
3. Select the + next to Documentation, and then select Add existing documentation.
4. Select the collection you want to use for API documentation.
5. Select Add Documentation. The API documentation is displayed in the Documentation tab.

You can add additional documentation collections from the Documentation tab. In the left pane, select the + next to Collection Documentation, and then select Add Existing Documentation.

Editing API documentation

You can add to your API documentation collections right from the Documentation tab. First, select a linked collection in the left pane. Then select the edit icon next to any description and use the built-in editing tools to author content.

Another way to work on your API documentation is to open the linked collection. In the Documentation tab, select View Collection at the upper right, and then edit the documentation in the linked collection.

Schema documentation cannot be edited in the Documentation tab. Instead, edit your schema in the Definition tab and then select Save. Postman automatically updates the API docs to reflect the latest schema changes.

Removing API documentation

To remove a linked documentation collection from an API:

1. Select APIs in the left sidebar, and then select an API and a version.
2. Select the Overview tab.
3. Select the remove button next to the collection you want to remove from this API version.
4. Select Remove Documentation.

Removing documentation only removes the link between the collection and the API version. The collection itself is not deleted.

Associating environments with documentation

An environment is a set of related variables you can use in Postman requests. You can also refer to variables when authoring descriptions in a collection. In each case, the initial value of the variable is automatically populated in the documentation.

Anyone using your collection will only be able to view the variables in the documentation if the associated environment is also shared with them. For public documentation, you can select an environment during the publishing process. Publishing an environment makes it available to anyone viewing public documentation.

To use an environment variable in your documentation:

1. Create a new environment if one doesn't already exist.
2. Make the environment active by selecting it in the environment dropdown list.
3. If needed, add a new variable to the environment.
4. Add a reference to the variable to requests or descriptions in your collection.

If someone imports a collection using the Run in Postman button from your documentation, they will also import the environment and any associated variables. The initial values for variables are published in your documentation, so make sure they don't contain any sensitive data.

Versioning your docs

A version is a set of features and functionality that your API delivers to consumers. A collection that contains API documentation can be linked to only one version of an API. That means, when you create a new version of your API, you'll also need to create a new documentation collection. You can then use the new collection to author documentation for the new API version.

There are several ways to create a documentation collection for a new version of your API:

• Carry over documentation when creating an API version. When you create a new API version, you have the option to copy elements from a previous API version into the new version. Select the Documentation element, and then select Create Version. This will create a new documentation collection based on the previous collection, with the new version name appended to the collection name.

  

• Generate a collection from the new API version. Open the new API version and select the Overview tab. Select the + next to Documentation, and then select Create new documentation.

• Add an existing to collection to the new API version. Open the new API version and select the Overview tab. Select the + next to Documentation, and then select Add existing documentation.

Postman automatically generates schema documentation for each version of your API, based on that version's API definition. Once you've versioned your API, you'll see a new version of the schema documentation in the Documentation tab.

Documenting releases

Releases are smaller, incremental units of change within an API version. You can include documentation changes as part of an API release. Anyone you share your collection with can use the Release tag dropdown list to view complete documentation for a specific release. For public documentation, you can choose which releases to include during the publishing process.

To document a new release of an API version:

1. Before creating the release, edit the API documentation as needed.
2. Create a new release of the API version.
3. If the documentation is public, edit the publishing settings to include the new release.

Next steps

Learn more about authoring your docs with Postman's built-in editing tools, publishing your docs to make them publicly available, and the various ways to view documentation.