Add API documentation in Postman

The API Builder provides one place to view, create, and manage all of your API's documentation. Postman automatically generates API docs for any OpenAPI 2.0 or 3.0 definition. You can also add detailed documentation to any API by generating a collection from the API or by adding a copy of an existing collection.

View schema documentation

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

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, minimum, and maximum values, and other constraints.

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

1. Select APIs in the sidebar and select an API.
2. 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, do the following:

1. Select APIs in the sidebar and select an API.
2. On the API's overview, next to Collections, select + and select Generate from definition.
3. 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.
4. Change any settings to customize the new collection.
5. 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.

Add existing documentation to an API

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

1. Select APIs in the sidebar and select an API.
2. On the API's overview, next to Collections, select + and select Copy existing collection.
3. 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 for an API, do the following:

1. Select APIs in the sidebar and select an API.
2. On the API's overview, select a collection and select View complete documentation.
3. Enter a description for any item. To learn more about using Postman's built-in editing tools, see Write your docs.
4. 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 an API, do the following:

1. Select APIs in the sidebar and select an API.
2. 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. 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 to make it available to consumers, go to Publishing an API version.

See how to document an API with a collection template that's a boilerplate for documentation that you can customize and reuse. To try out this template, select API documentation.