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.

Contents

• Generating your documentation

  • Documenting an existing collection
  • Creating documentation for a new collection
  • Including detail in your docs
• Accessing doc views
• Documentation environments
• Versioning your docs
• Next steps

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.

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.

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

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

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.

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

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.

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

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

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.

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.

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

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.

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.

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

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

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

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

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.

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

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

Next steps

Learn more about authoring your docs and publishing them.