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 Postman, 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

You can edit your docs either in Postman, or directly in the browser (while viewing documentation for a collection you have edit access to).

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 carry out additional edits directly on the documentation page—you'll see editable areas highlighted on hover. Click to edit, make your changes, and save them to update the text.

Edit Header

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, required authorization type, URL, description, headers, request and response structures, and examples. In both private and public documentation, all key-value pairs in headers, parameters, and request bodies will be displayed for each request.

Request details

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 Postman 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

If you edit your docs in the browser, you'll see helpers for a few common options and the ability to preview your changes.

Edit Description

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.

Your documentation receives a number of free views per month and is dependent on your Postman plan beyond that. 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 Postman.

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

You can reference variables in your description text to show the values in your documentation.

Inline Documentation Edit with Variable

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.