Viewing documentation

Documentation helps you get more out of the collections and APIs that you work with in Postman. View documentation to learn more about the requests in a collection or how to interact with an API's endpoints.

By default, documentation for a collection is private. You can view the documentation for any collections that have been shared with you directly or through a team workspace.

Documentation authors can also choose to publish their documentation to make it publicly available. Anyone in the world can view the public documentation using a web browser. If the associated collection is in a public workspace, people can also view the collection in Postman.

Contents

Viewing documentation for a collection

In Postman, documentation is always associated with a collection. You can view the documentation for any collection that you created or for collections that have been shared with you.

Postman teammates with the Viewer role can view documentation, while teammates with the Editor role can also create and update documentation. Learn more about roles and permissions.

To view documentation for a collection:

  1. Select Collections in the sidebar, and then select a collection, folder, or request.

    You can also search for collections on the Public API Network.

  2. Select Documentation Documentation icon in the context bar to view documentation for the selected item.

  3. To view all of the documentation for the collection, select View complete collection documentation.

View complete documentation

The documentation includes a description of each request, as well as details such as the method and URL, the required authorization type, and any headers or parameters. For each request, you can view sample code in various client languages, together with example response bodies and headers.

Use the following options to customize the appearance of the documentation:

  • Release Tag: If the documentation has multiple release tags, you can select a specific release to view.
  • Language: Select a language to use for sample code.
  • Code Generation Settings: Select the gear Code generation icon to customize settings for the currently selected language.

Viewing a release

Another way to view documentation is to visit your user profile. Select the Collections tab to see collections that have been shared with you as well as your own collections. Select a collection to view its documentation.

Viewing API documentation

API developers can generate API documentation to help consumers understand and interact with their API's endpoints. To make documentation available on the API's Documentation tab, you must either create a new collection for the API documentation or add an existing collection.

To view documentation for an API:

  1. Select APIs in the sidebar, and then select an API and a version.

    You can also search for APIs on the Private API Network or the Public API Network.

  2. Select the Documentation tab.

Use the navigation menu on the right to jump to a particular endpoint. To see sample code in a different language, select it in the Language menu.

Viewing a release

Viewing public documentation

Public documentation is hosted on the web by Postman. To access public documentation, simply enter the documentation URL in the address bar of your web browser. The URL is generated by Postman during the publication process.

For each request, you will see a description of the request, the method and URL, the required authorization type, and any headers or parameters. You will also see sample client code for the request, along with example response bodies and headers.

Use the options in the header to customize the appearance of the documentation:

  • Release Tag: If the documentation has multiple release tags, you can select a specific release to view.
  • Environment: If an environment was published with the documentation, you can select it to populate any variables.
  • Layout: Double column displays sample code in a column to the right of the documentation. Single column displays sample code inline beneath each request.
  • Language: Select a language to use for sample code.
  • Language Settings: Select the gear Language settings icon to customize settings for any of the available languages.

Published documentation example

Postman supports various programming languages and frameworks for displaying sample code. Don't see your language of choice, or is there a setting missing that you'd find useful? Select the gear Language settings icon and then select Contribute on GitHub to contribute to the open-source project.

Linking to public documentation

Want to share a specific endpoint with someone or bookmark it for later? You can save links to sections in public documentation, including the introduction, requests, folders, and responses.

To save a link, select a section, folder, or request in the left sidebar. Copy the URL in your browser's address bar, or save it as a bookmark. Next time, you can use the URL to link directly to the selected section.

Documentation links

Next steps

Learn more about collaborating with your team in Postman.

Last modified: 2021/12/08