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 the Postman editor to see exactly how your content will look as you author it. Or use the classic Markdown editor to structure and format your descriptions using Markdown syntax. 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 icon Edit icon next to the description.

  4. Author your description using the visual Postman editor or the classic Markdown editor. Both are compatible, so feel free to switch between the two editors as you work.

    Switching editors
  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 the Postman editor

To author a description using rich text editing tools, select the Postman editor option. The Postman editor makes it easy to author a description without having to write any Markdown code. Use the tools on the toolbar to work with text and other content, just like in a typical word processor. Or use common keyboard shortcuts to format text, like ⌘+B or Ctrl+B to make text bold. There's no need to preview your content to see the final appearance—what you see is what you get!

Postman editor

View the tooltips to get help as you work. Hold your cursor over an item on the toolbar to see a description of the tool and the associated keyboard shortcut. If all of the tools are not visible on the toolbar, select the three dots Three dots icon.

Postman editor toolbar

Working with tables is fast and easy. No need to fuss with Markdown code to get your tables to work. To add a table, select the Table tool. To add or remove columns or rows, or to delete the table, select a cell and then select the shortcut menu.

Postman editor table shortcuts

The Postman editor understands Markdown syntax. If you're comfortable using Markdown, type any standard Markdown code to quickly format text. For example, type # followed by a space to start a new heading, or type --- to add a horizontal line. To reuse documentation that's already written in Markdown, just copy the existing Markdown code and paste it into the editor to instantly format it.

If you copy content from the Postman editor, the content will retain its formatting when you paste it into another application like a word processor or an email.

Using Markdown shortcuts

Authoring descriptions in Markdown

To author a description using Markdown, select the Classic Markdown editor 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 the Postman editor, select the Link tool. Paste or type the URL and the link text, and then select Add. (If you need to change the link later, select it and then select the edit icon Edit icon.)

    Adding a link
  • 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 the Postman editor, select the Image tool. Paste or type the image URL, and then select Add. (If you need to change the image later, select it and then select the edit icon Edit icon.)

    Adding an image
  • 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.

Last modified: 2021/12/09