Authoring your docs

You can include information in your API documentation using Markdown. Postman will populate various parts of your documentation from the information associated with the relevant collection. Your Markdown content can include standard structures and formatting such as headings, lists, images, links, bold / emphasis, code samples, blockquotes, and tables. You can author documentation either from the collection in Postman, or directly in the docs when viewing them in the web browser.

Contents

Documenting with descriptions

You can add descriptions to various places within your collections and requests, and they will appear in your documentation. You can include descriptions for collections, requests, parameters, and headers. You can also edit directly on the web for any documentation on a collection you have edit access to.

Describing collections

You can include Markdown descriptions in your documentation, for collections and the requests within them.

You can add a description when you create a collection, or by selecting the collection and using the arrow button (▶).

Add Description

When you include block elements, leave an empty line before and after to avoid any rendering issues.

You can also edit descriptions in the web browser when you view documentation for collections where you have edit permissions.

Edit Description

Documenting request detail

You can provide a description when you create a new request or for an existing request at any time.

When you create a new request using the New button, you will be prompted to provide a name and description (which can include Markdown), both of which will appear in your documentation.

Request Description

To add a description to an existing request, open the request in Postman and edit the request detail.

Edit Request

Request Description

Descriptions will appear in the request section in your documentation.

Request Description in Docs

You can also edit the request detail including the description directly from your docs in the browser—editable text will highlight on hover.

Edit Docs

Click to edit a section of text.

Edit Request Name Edit Heading

Make your changes, and save them.

Edit Request

You will see a warning if your documentation contains any unsaved changes.

Unsaved Edit

Parameters and Headers

You can add a description to the parameters and headers in your requests—for people viewing the request inside Postman (for example if you're working on a shared collection), or for anyone viewing your documentation.

Parameter Description

All key-value pairs will be displayed in your documentation regardless of whether or not they're checked. You can indicate which pairs are required and which are optional in the description. Consumers of your documentation can choose which key-value pairs they want to use when they send requests to your endpoints. Users will be able to generate code snippets in the Postman app based on the key-value pairs they select, and a URL with those pairs will be displayed in the app.

The description will appear in your docs, in the request Params and Headers sections, next to the parameter or header name.

Header Description in Docs

Authorization details

You can include the type of authorization required to access your APIs in your documentation. You can add your authorization details at the collection level or at the request level. Authorization requirements added at the collection level apply to each request and will be displayed for each one in your documentation.

Docs Link

If one of your endpoints requires an authorization type that varies from the collection, you can add that authorization type to the request in the request tab, and it will be rendered in the documentation.

Auth display

Using examples in your docs

You can include example request and response data in your collections, and they will appear in your documentation.

Any body data included in your request will appear in the endpoint section of your documentation.

Body Data

You can also create an example to use for a request. Click Examples > Add Example.

Add Example

Create the example you want to add and click Save Example.

Body Example

Any data you include in the example will appear on the right, in the docs example code sidebar, as the response body and headers.

Learn more about viewing documentation.

Examples in Docs

Postman currently supports various programming languages and frameworks to customize your code snippets.

Don't see your language of choice, or is there a setting missing that you'd find useful? Click Contribute on GitHub under the settings icon to contribute to the open source project.

[code snippets settings](https://i.imgur.com/tEfZ2ry.png)

You can link to headings within your generated documentation, including the introduction, requests, folders, and responses.

The links are generated from your documentation using IDs. To find a link, click the relevant section in the left sidebar and you'll see it in your browser address bar (or right-click and copy the link). You can then link directly to doc page sections using this link.

Documentation Links

You cannot link to another part of the documentation by manually creating an ID.

Using images in docs

You can include any image you have hosted online in your documentation. Use the Markdown image syntax as follows:

![Image Alt Text](https://your-image-location.com)

Markdown demo collection

You can use the Postman Markdown collection to see how Markdown is rendered in documentation and the Postman app.

markdown reference

You can also see examples of documentation published using Postman collections by browsing the templates. Click New, select the Templates tab, choose a template, and click View Documentation.

Template Docs

The Postman API documentation is authored using Postman.

If you edit your docs on the web, (following the links from your collection in the Postman app, or the dashboard when logged into your account in the browser), you will see helpers for common formatting options and be able to preview your changes.

Inline Edit Options

Next steps

To make your documentation publicly available, check out Publishing your docs.