Skip to navigation
CollaborateDocument APIsPostman documentation

Document a collection in Postman

View as Markdown

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 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. In the left sidebar, choose 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. Click outside of the editor to save your new content.

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

  1. In the left sidebar, choose a collection and then a request.
  2. Click the Docs tab.
  3. Enter a description. To learn more about using Postman’s built-in editing tools, see Write your docs.
  4. Click outside of the editor to save your new content.

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

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 shared value of the variable is automatically populated in the documentation.

Anyone using your collection can view the variables in the documentation if the associated environment is also shared with them. For public documentation, you can choose 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 choosing 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 also import the environment and any associated variables. The shared 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.