Table of contents
1.
Introduction🤔
2.
Documenting a Collection🎯
3.
Generating API Documentation🦾
3.1.
Viewing Schema Documentation🏄🏻‍♀️
3.2.
Creating New Documentation For an API🏄🏻
3.3.
Adding Existing Documentation to an API🏄🏻‍♂️
3.4.
Editing API documentation🏂🏻
3.5.
Removing API documentation🛒
4.
Associating Environments with Documentation⚡
5.
Versioning Your Docs🌐
5.1.
Documenting Releases🏊🏻‍♂️
6.
Frequently Asked Questions
6.1.
What is a postman?
6.2.
What does API stand for?
6.3.
What is API used for?
6.4.
What workspace is used for in postman?
6.5.
What collection is used for in postman?
6.6.
What is the difference between versions and releases?
7.
Conclusion
Last Updated: Mar 27, 2024

How to Document an API in Postman

Author Sanchit Kumar
0 upvote
Career growth poll
Do you think IIT Guwahati certified course can help you in your career?

Introduction🤔

Documentation is a crucial part of any collection or API. Good documentation helps people to understand what your API does and how each request works. And thorough API documentation lets your customers know about the various endpoints and how to interact with them.

So let us learn how to document an API in postman.😺

how to document

Are you ready❓

Documenting a Collection🎯

To document an API first, you need to learn about documenting a collection. For any collection you create, the postman automatically generates raw documentation.

create new collection


The documentation displays all key-value pairs for headers, request parameters, and bodies. Request details include the method, authorisation type, URL, headers, request and response structures, and examples.

To make your documentation valuable to your users, you can add descriptions to the items in your collection.
 

For adding the description, follow the given below steps -

  • Select the Collections from the sidebar, and select a collection, request or folder.
collection
  • Now, select the documentation icon in the context bar.
documentation
  • To edit, select the edit icon present next to the description.
edit description
  • Compose new content and then select save.
description
note

The next step in learning to document an API is generating API documentation. So let us dive into it.

Generating API Documentation🦾

Your API's documentation can be seen, created, and managed in one location using the documentation tab in the API builder. The postman automatically generates API docs for any OpenAPI 3.0 schema defined in the API builder. Detailed documentation to any API can also be added by generating a collection from the API or linking to an existing collection.

note

If you create a new version of the API, you will also need to generate a new collection to hold that version's documentation which means a collection can be linked to only one version of an API. 

Viewing Schema Documentation🏄🏻‍♀️

Postman automatically creates documentation based on your defined schema if you develop an API based on the OpenAPI 3.0 specification.
 

Follow given below steps to view the documentation for an OpenAPI 3.0 schema -

  • From the sidebar, select APIs, and then select an API and version.
select apis
  • Now, select the documentation tab.
  • Select an item under schema documentation in the left pane to view a specific path or request.
schema documentation

Creating New Documentation For an API🏄🏻

Generating new collection for the API documentation - 

  • From the sidebar, select APIs, and then select an API and version.
select apis
  • Select - The overview tab.
overview tab
  • Next to documentation, click on the + and then select create new documentation.
create new documentation
  • Input a name for the new collection.
  • If you want to change any settings, select show advanced settings and as needed (Optional).
create documentation
  • Click on the create documentation. You will see the new API documentation in the documentation tab.
documentation added

Adding Existing Documentation to an API🏄🏻‍♂️

Follow the given below steps to use an existing collection to document an API or API documentation -

  • From the sidebar, select APIs, and then select an API and version.
select apis
  • Now select the Overview tab.
overview tab
  • Next to documentation, click on the + and select add existing documentation.
add existing documentation
  • Select the collection from the list you want to use for the API documentation.
add documentation
  • Click on the Add Documentation. You will see the new API documentation in the documentation tab.
name of the collection

Editing API documentation🏂🏻

From the documentation tab, you can add to your collections of API documentation. First, from the left pane, select a linked collection. Then click on the edit icon next to any description and use the built-in editing tools to author content.

collection documentation


Another way to deal with your API documentation is to open the linked collection. Select view collection at the upper right in the documentation tab, and then edit the documentation in the linked collection.

selected collection documentation


You can edit schema documentation in the definition tab and click on save. Postman automatically updates the API docs to show the latest schema changes.

definition tab

Removing API documentation🛒

To remove a linked documentation collection from an API -
 

  • From the sidebar, select APIs, and then select an API and version.
select apis
  • Now, select the Overview tab.
overview tab
  • Click on the remove icon next to the collection you want to remove from this API version.
remove
remove documentation
  • Click on the remove documentation.
documentation removed

Note - Removing documentation does not delete the collection but only removes the link between the collection and the API version.
 

Now, after generating API documentation, you need to learn about associating environments with documentation to document an API.

Associating Environments with Documentation⚡

A set of related variables is an environment which can be used in postman requests.
 

Follow the given below steps to use an environment variable in your documentation which is a crucial part when you document an API - 

  • Create a new environment if the environment does not already exist.
create environment
  • Make the environment active by clicking on set active in the environment dropdown list.
set active
  • You can add a new variable to the environment if you want.
new variable
  • You can also add a reference to the variable to requests or descriptions in your collection.

Versioning Your Docs🌐

A version is a set of features and functionality your API delivers to consumers.

There are many different ways to create a documentation collection for the new version of your API - 

Carryover documentation when creating an API version - 

create version

While you are creating a new API version, you can copy elements from the older API version into the new version. Now, select the documentation element and click on create version to create a new documentation collection based on the older collection, with the new version name appended to the collection name.

create new version

Note - You can generate a collection from the new API version or add an existing collection to the new API version.

Documenting Releases🏊🏻‍♂️

Releases are minor and incremental changes made to an API version. After you document an API, changes to the documentation may be included in an API release. Anyone with access to your collection can browse detailed documentation for a particular release by selecting it from the release tag dropdown list. You can choose which releases to include for public documentation during the publishing process.
 

Follow the given below steps to document a new release of an API version - 

  1. Edit the API documentation as needed before creating the release.
  2. Create the new release of the API version.
  3. Edit the publishing settings to include your new release if the documentation is public.
     

We hope you have understood everything about how to document an API in Postman.🙌

Frequently Asked Questions

What is a postman?

Postman is an API platform for building and using APIs.

What does API stand for?

API stands for Application Programming Interface.

What is API used for?

API is a software intermediary that allows two different applications to communicate with each other.

What workspace is used for in postman?

Postman workspaces are used to organise API work and collaboration across organisations and the world.

What collection is used for in postman?

A collection in postman helps us to group similar requests. It helps in systematically arranging the requests into folders.

What is the difference between versions and releases?

Version represents a specific edition or form of something at a specific point in its history. On the other hand, the release is the distribution of the newest version of a document or application.

Conclusion

This article discussed how to document an API in postman. We learn documenting a collection, generating API documentation, associating environments with documentation, versioning your docs and documenting releases.

See the official website for documentation and other information about Postman, or you may refer to our blogs on APIAPI testing and web testing.

We believe this article on how to document an API in postman was helpful.

Refer to our guided paths on Coding Ninjas Studio to learn more about DSA, Competitive Programming, JavaScript, System Design, etc. Enrol in our courses and refer to the mock test and problems available. Take a look at the interview experiences and interview bundle for placement preparations.

Happy Learning Ninja! 🥷

Live masterclass