Add API documentation in Postman

You can view, create, and manage your API's documentation either with collections or the Postman API Builder. You can add detailed API documentation to a collection by turning on types in the collection. This enables you to add more details to request parameters, headers, and bodies in an HTTP collection. With the API Builder, you can also add detailed documentation for any OpenAPI 2.0 or 3.0 definition. You can then generate a collection from the API or add a copy of an existing collection.

The API documentation includes complete API, path, and operation information, such as authentication methods, parameters, request bodies, response bodies and headers, and examples. The documentation also includes information for various data models, such as required attributes, default values, minimum and maximum values, and other constraints.

Add API documentation with collections

Postman automatically creates documentation for a collection you create. With types in collections, you can build out this documentation by designing your API with the Postman Collection format. When you turn on types in an HTTP collection, you can add more details, such as type and possible values, to request parameters, headers, and bodies in the collection. Details you add appear in your collection's documentation.

To get started, turn on types in a collection. Then you can add properties to parameters and headers, and you can add properties to body data in your requests.

To view the documentation for a collection with types turned on, do the following:

Select Collections in the sidebar, then select a collection with types turned on.
Select the collection's Overview tab and select View complete documentation.

View documentation for a collection with types

Add API documentation with the API Builder

If you are designing an API in the API Builder based on the OpenAPI 2.0 or 3.0 specification, Postman automatically creates documentation based on your API definition.

With the API Builder, you can create documentation from a new collection or an existing collection. You can also edit a collection's documentation and delete a collection if you no longer need it.

To view the documentation for an OpenAPI 2.0 or 3.0 API from the Postman API Builder, do the following:

Select APIs in the sidebar and select an API.
On the API's overview, under Definition, select View schema documentation.

You can also view schema documentation while editing your OpenAPI 2.0 or 3.0 definition. Postman displays a live preview of the documentation as you work on your API. Learn more about previewing schema documentation.

Create new documentation for an API

To generate a new collection for API documentation from the Postman API Builder, do the following:

Select APIs in the sidebar and select an API.
On the API's overview, next to Collections, select Add and select Generate from definition.
Select the checkbox if you want Postman to suggest updates for the collection when the API definition changes. This checkbox is selected by default. Learn more about keeping a collection in sync with an API.
Change any settings to customize the new collection.
Select Generate Collection.

The new collection displays on your API's overview and under your API in the sidebar. To view documentation for the collection, select the collection and select View complete documentation.

You can also generate a collection from Spec Hub. Postman automatically creates a collection with folders, requests, and response examples based on the specification.

Add existing documentation to an API

Copy an existing collection with API documentation to an API.

If you copy a collection with types turned on, properties won't be copied to the new collection linked to the API.

To use an existing collection for API documentation in the Postman API Builder, do the following:

Select APIs in the sidebar and select an API.
On the API's overview, next to Collections, select Add and select Copy existing collection.
Select an available collection and select Copy Collection.

The copy of the collection displays on your API's overview and under your API in the sidebar. To view documentation for the collection, select the collection and select View complete documentation.

When you add a collection, an independent copy of the collection is added to the API. The copy in the API will no longer be in sync with the original. If you move or delete an API, any collections contained in the API are moved or deleted with it.

Edit API documentation

You can add to your API documentation collections from the API Builder.

To edit a documentation collection from the Postman API Builder, do the following:

Select APIs in the sidebar and select an API.
On the API's overview, select a collection and select View full documentation.
Enter a description for any item. To learn more about using Postman's built-in editing tools, see Write your docs.
Select outside of the editor to save your new content.

Schema documentation can't be edited directly. Instead, edit your API's definition and then select Save. Postman automatically updates the API docs to reflect the latest changes to your definition.

Delete API documentation

To delete a documentation collection from the Postman API Builder, do the following:

Select APIs in the sidebar and select an API.
On the API's overview, select the more actions icon next to a collection and select Delete.

Next steps

After adding documentation to an API in Postman, you can edit and format the docs. You can also publish your API, including the documentation.

To learn more about adding descriptions to a collection, including collections linked to an API, go to Document a collection.
To learn more about editing and formatting your documentation, go to Write your docs.
To learn how users can access your documentation, go to View documentation in Postman. By default, your documentation is private, so you must share an API with others before they can access it.
To learn how to publish your API in the Postman API Builder to make it available to consumers, go to Publish a version of your API for consumers in the Postman API Builder.