Documentation in general terms is the written material that provides or serves as official evidence or information. When we talk about documentation, we are generally talking in terms of learning or gathering information about certain things. This depends on the subject of documentation. For example, documentation of a certain specimen in the laboratory will provide information about that specimen to the doctors. In the IT world, documentation of different software, tools, and APIs help you learn about those things from trusted sources (official) and in a correct way. This takes us to the API Documentation in Postman. To index our tutorial, we will learn:
- What is API Documentation?
- Need for API Documentation.
- API documentation in Postman.
- How to Generate API Documentation in Postman?
What is API Documentation in Postman?
The API documentation is a well structured written material that provides third-party users to use the API efficiently. This includes the step-wise process and instructions on how to use your API. This documentation enables the third party users/developers to understand the usage of your API very quickly. Given below is the documentation for Paypal API
Writing API documentation requires a very good understanding of the API, its use, programming language used and response. Good API documentation should be able to convey the complex process in a simple and easy manner with good detailed instructions.
Why API Documentation is required and important to have?
As throughout this course we have learned how to use the APIs and execute tests on them. As you must recall, we used our own API to demo some of the features of Postman to you. Since APIs are constructed by every company which allows it to use them, they need a well structured official document to guide developers on how to use it. This is very important as what is the point of developing something great when nobody is able to use it? The API developing corporation is not the only user of its API. Third-party developers make a good percentage of users. Since API serves as a middleman to make use of the product, documentation serves as a platform to make use of API. Without good API documentation, the product cannot be used which in turn will incur a loss for the organization. This goes for small businesses, budding startups and individuals like you. Anyone who is willing to share his API must have documentation for the people to guide them. Therefore, API documentation is as important as an API and in our case, this is done by Postman. We will see how in the next section.
You can visit the API documentation pages I have mentioned here which are quite popular among the developers:
API documentation using Postman
Postman helps us create API documentation with the help of a few clicks. It is a great way instead of writing your own documentation from scratch and publishing it on your own. Before we proceed to actually publish the documentation, you must make note of a few things.
It is not advisable to publish documentation without your company's knowledge. Once you sign in to Postman app, all your local collections and requests are synced to the Postman cloud. This will sync your documentation too as you cannot publish API documentation in Postman without signing in. In other words, your documentation will become public and will be accessible to anyone. To make your postman private, you need to be a Postman Enterprise or Postman Pro member. If you are, you can share your documentation within your team or organization privately.
You should also note that only 1000 views are allowed on the documentation per month. It is the same for all the plans in Postman. After your 1000 views are completed, your documentation will not be accessible until 30 days are completed. Starting with this, let us publish documentation in Postman.
How to Generate API Documentation in Postman?
-
Open your Postman application (Make sure you are signed out).
-
Import the collection from here. (Refer How to import collections in Postman).
-
Once you have imported your collection, you will see it in the sidebar.
- Now, select the small arrow that appears beside the collection name when you hover the mouse over it.
-
This will open up a new panel.
-
Select the edit icon on the description to edit the description.
- Write a description of your choice in the text box and press Save.
- Press the menu button alongside Share and Run at the top to open multiple options. Press Publish Docs in the options.
- You will get a sign in prompt. If you were already signed in, you will jump to point number 12.
- Sign in to the Postman. Once you sign in, you will see a new button will appear beside Share and Run option.
-
This option can be used to view the documentation temporarily as it would like after publishing. Coming back to Publish Docs Option. Press the Publish Docs option as discussed in point 8.
-
This option will open up a web page in your browser to select your environment name.
Note: You can refer to the Environment and Variables in Postman tutorial to know more about the environment.
- Choose the appropriate environment for the collection.
-
You can also click on the Show Custom Styling Options to change the colour scheme of the documentation.
-
Click on Publish Collection to publish the collection.
Note: Let all users discover this collection in the Postman app is used for letting your collection available to the Postman family. For this, your API should be one which is not specific to you but can be used by anyone learning or expert. It should have a defined workflow since it will be seen by the Postman community publicly.
16. You will see this web page that your collection is published.
You can edit or unpublish your collection from this screen. You will get a published public URL for your documentation.
- Visit the URL to see your published API documentation.
What gets automatically generated?
Since you own written API Documentation can have any number of fields, only a few and important fields are created when we create the documentation using Postman. So your documentation will include:
-
Collection and Request names.
-
Descriptions associated with requests, folders, and collections. This will also contain the method type, headers and body code (if any).
- Generated code snippets in some of the most popular programming languages.
- A link to run the collection directly in Postman along with the dropdown to change the environment.
Postman uses ordered requests and folders to organize documentation in sections to reflect the structure of your collection. You can customize descriptions using Markdown styling with embedded graphics to complement your documentation. Postman supports GitHub-flavored Markdown so you can include tables. When including block elements, make sure you leave an empty line before and after to avoid any rendering issues.
You can now share this documentation to whomsoever you want to use your API. You can find more options here and there to edit the documentation in one way or other. Involve yourself in this for some time to extract every detail about the documentation and it will definitely help you in the future. As I discussed above, an API is useful as long as it's documentation is crisp and understandable.
