Document a collection in Postman

Postman automatically generates basic documentation for any collection you create. The documentation includes details about 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.

Add descriptions to a collection

Add descriptions to your collections (including collections linked to an API) to enhance your documentation and add more detail. You can use the Postman editor to view how your content will look as you write it, or use standard Markdown syntax to write content. With either editor, you can format text, add links, and insert images and videos in your documentation.

To add a description to a collection or folder, do the following:

1. Select Collections in the sidebar, and then select a collection or a folder.
2. Enter a description in the Overview tab. To learn more about using Postman's built-in editing tools, see Write your docs.
3. Select outside of the editor to save your new content.

To add a description to a request, do the following:

1. Select Collections in the sidebar, and then select a request.
2. Select the documentation icon in the right sidebar.
3. Enter a description in the right sidebar. To learn more about using Postman's built-in editing tools, see Write your docs.
4. Select outside of the editor to save your new content.

You can also edit descriptions when viewing the complete documentation for a collection. Select a collection in the sidebar, then select View complete documentation in the Overview tab. From here, you can add a description to any item in the collection.

Document gRPC and WebSocket collections

Collections with gRPC or WebSocket requests use a different format than collections with HTTP requests. You can view documentation and add descriptions for gRPC or WebSocket requests. You can also add a description on the collection's Overview tab, but you can't view or edit documentation for the full collection. Learn more about documenting gRPC requests or documenting WebSocket requests.

Associate environments with documentation

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

Anyone using your collection will 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, do the following:

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.

Next steps

After documenting a collection in Postman, you can edit and format the docs and publish them.

• To document an API in Postman, go to Add documentation to an API.
• To learn more about editing and formatting your documentation, go to Write your docs.
• To learn how users can access your documentation, go to View documentation. By default your documentation is private, so you must share a collection with others before they can access it.
• To make your documentation publicly available, visit Publish your docs.

See how to document an API with a collection template that's a boilerplate for documentation that you can customize and reuse. To try out this template, select API documentation.