Authoring your docs

Postman automatically generates documentation for every collection you create. The documentation includes all of the requests in your collection, along with examples, authorization details, and sample code.

To help your teammates (or the world) better understand what you're building, add detailed descriptions to your collection and the items in it. Use standard Markdown syntax to structure and format your descriptions. All of your descriptions are included in the documentation for your collection.

You can also add a description when creating a new request.

Contents

Adding descriptions to your documentation

Use descriptions to tell people who use your collection more about what your collection does and the purpose of each of request. Structure your descriptions with headings and add content such as text, tables, images, and links.

To add or edit the description for an existing collection, folder, or request:

  1. Select Collections in the sidebar, and then select a collection, folder, or request.
  2. Select Documentation Documentation icon in the context bar.
  3. Select the edit button Edit icon next to the description.
  4. Author your description using Markdown.
  5. When you're finished, select Save to save your documentation. If you ever need to make changes, just edit the description again.

To give users even more details about requests in your collection, add descriptions to the request parameters and headers.

Authoring descriptions in Markdown

To author a description using the Markdown editor, select the Markdown option. Use standard Markdown syntax to create your content:

  • Structure content with headings, lists, and tables
  • Format text with bold, emphasis, and blockquotes
  • Add images, links, and code blocks

As you work, select the Preview tab to see how your documentation will appear and to make sure it's formatted correctly. To continue editing, select the Markdown tab.

Leave a blank line before and after block elements (such as headings, paragraphs, and lists) to avoid any formatting issues.

Markdown editor

Adding descriptions to parameters and headers

Add descriptions to parameters and headers to help others understand and use the requests in your collection. Open a request and type the description in the box next to the key-value pair.

Parameter descriptions

The parameter and header descriptions are visible to people who have access to your collection or anyone viewing your published documentation. The descriptions appear in the documentation along with the request, next to the parameter or header name.

All key-value pairs are included in your documentation even if their check boxes are not selected. Use the description to note which parameters and headers are required and which are optional. Anyone using your collection can choose which key-value pairs to include when sending requests or generating code snippets.

Including authorization details

Your documentation automatically includes the type of authorization required to access your endpoints. The authorization details appear below the collection description and also below each request in your documentation.

If you specify authorization details for the collection, those authorization requirements are inherited by every request in the collection. If one of your endpoints requires a different authorization type, open the request and change the authorization details. The changes are reflected in your documentation.

Authorization type in documentation

Including examples

Examples are paired requests and responses that demonstrate your endpoints in action. Any examples you add to a collection are automatically included in the documentation. For each request, your documentation shows the example code snippets as well the example response body and headers.

Examples are displayed only when you view the complete documentation for a collection or when you view published documentation.

Examples in documentation

Use links to direct users to your repository, web site, or other online resources.

To add a link using Markdown, use the the following syntax:


[link text to display](https://your-link-url.com)

Adding images

Images liven up your documentation and help your ideas come across more clearly. Your image must be hosted online before you can add it to your documentation.

To add an image using Markdown, use the following syntax:

![image alt text](https://your-image-location.com)

Finding help and inspiration

Need some help using Markdown? Check out the Postman Markdown demo collection to see how Markdown is formatted in published documentation. Select the Run in Postman button to add the demo collection to your workspace and view the Markdown code.

Markdown demo collection

Looking for some documentation inspiration? Browse through the Public API Network to find examples of great documentation created in Postman.

  1. Navigate to the Public API Network page or select Explore in the Postman header.

  2. Select Teams, Workspaces, APIs, or Collections in the left pane.

    Public API Network page

  3. Select a team, workspace, API, or collection to see documentation authored by others who are part of the Public API Network.

    Documentation example

Next steps

To make your documentation publicly available, see Publishing your docs.