Documenting your API

You can automatically generate documentation for your Postman APIs. You can share your documentation privately or publish it on the web. Postman generates and hosts documentation based on collections, synced in realtime and accessible via the browser. You can use documentation to collaborate with team members and partners, or to support developer adoption for your public APIs.

Public Documentation

Contents

Generating your documentation

Documentation is based on a Postman collection, so you can generate it from an existing collection or create it in conjunction with a new collection.

Documenting an existing collection

To generate and view documentation for an existing collection from the Postman app, use the Collections tab on the left to select the collection. Use the arrow (▶) button to open the collection detail, and select View in web to open the documentation in the browser.

View Docs

Alternatively, use the New button, and select API Documentation. Choose Select an existing collection and click the collection you want to view docs for.

Document Collection

Enter or edit the markdown description of your collection and click Save.

Collection Description

You will see a confirmation that your documentation is published, and a link you can visit to view it in the browser.

Docs Link

You can also view documentation from the web dashboard—select View all collections, then select a collection to view its docs in the browser.

Collections in Web

By default your documentation is private, so only people you share the collection with will be able to see it. You can publish your documentation for public viewing.

Some detail is included in your documentation by default, and you can optionally add further detail.

Creating documentation for a new collection

You can create documentation from the Postman launch screen or using the New button and choosing API Documentation. Create a new collection will be selected by default. Add any initial requests you want to document within your new collection and click Next.

Document Request

Name the collection, enter a markdown description to display in your docs, and click Save.

Collection Description

You will see a confirmation that your documentation is published, and a link you can visit to view it in the browser.

Docs Link

By default your documentation is private, so only people you share the collection with will be able to see it. You can publish your documentation for public viewing.

Including detail in your docs

Your docs will automatically include detail on your requests, with sample code in various client languages. Each collection / request listing indicates the method, URL, description, headers, request and response structures, and examples. Private docs include a link to share the associated collection, and public docs include a Run in Postman button, allowing viewers to import the collection directly into the Postman app to try your requests out. Your documentation page will be structured to reflect the folders and requests in your collection.

You can add detail to your descriptions using Markdown. Postman supports GitHub-flavored Markdown, so you can include various types of content, such as lists, tables, images, and links.

Docs Folders

For more on adding detail to your docs, see Authoring your documentation.

Accessing doc views

By default your documentation is private, and viewable only to people you have shared a collection with. If you publish your documentation, anyone with the link can view it in a browser.

For more on accessing private and public docs, see Viewing documentation.

Public and private documentation pages receive 1000 free views per month. You can check your usage limits through the Postman API or the account usage page.

Documentation environments

You can use environments to set variables that will be available in your documentation. Anyone viewing private documentation will be able to access environments shared with them. For public documentation, you can select an environment to share during the publication process—this will make the environment available to anyone viewing the published documentation link.

Doc Environment

Associating an environment with your documentation means that the values of any environment variables your requests reference will automatically populate in the doc content. Anyone using the Run in Postman button from your docs will also be able to access the shared environment when they import the collection into their Postman app.

To use a variable value in your documentation, create or select an environment.

Environment Quick Look

Add the new variable if you haven't already done so.

Environment Variable

When you reference a variable in your requests, the value from the selected environment will automatically be published along with your documentation.

Reference Variable

This means that anyone viewing your documentation will see the variable value along with the relevant environment.

Variable Value in Docs

If someone imports the collection using the Run in Postman button from your docs, they will also import the environment and variable.

Variable values will be published explicitly in your docs, so make sure they don't contain any sensitive data.

Versioning your docs

Any version tags you add to your collections will be published along with your docs. You can add versions to an API or collection.

Add Version

If you share a collection privately, viewers will be able to select versions from a drop-down list in your docs.

Docs Versions

When you publish docs to share publicly, you can select a version all viewers will see.

Publish Version

Next steps

Learn more about authoring your docs and publishing them.