Do you think IIT Guwahati certified course can help you in your career?
No
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.😺
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.
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.
Now, select the documentation icon in the context bar.
To edit, select the edit icon present next to the description.
Compose new content and then select save.
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.
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.
Now, select the documentation tab.
Select an item under schema documentation in the left pane to view a specific path or request.
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 - The overview tab.
Next to documentation, click on the + and then select 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).
Click on the create documentation. You will see the new API documentation in the documentation tab.
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.
Now select the Overview tab.
Next to documentation, click on the + and select add existing documentation.
Select the collection from the list you want to use for the API documentation.
Click on the Add Documentation. You will see the new API documentation in the documentation tab.
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.
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.
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.
Removing API documentation🛒
To remove a linked documentation collection from an API -
From the sidebar, select APIs, and then select an API and version.
Now, select the Overview tab.
Click on the remove icon next to the collection you want to remove from this API version.
Click on the remove documentation.
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.
Make the environment active by clicking on set active in the environment dropdown list.
You can add a new variable to the environment if you want.
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 -
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.
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 -
Edit the API documentation as needed before creating the release.
Create the new release of the API version.
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 API, API testing and web testing.
We believe this article on how to document an API in postman was helpful.