This Tutorial Explains How To Create Good Looking, Styled Documentation with Minimal Efforts Using the API Documentation Support Provided by Postman Tool:
For any API, whether Internal or Public-facing, documentation is one of the most essential ingredients for its success.
The prime reason for that is, documentation is the way you communicate with your users.
- How your API should be used?
- What all status codes are supported?
- What are the error codes?
- What all Method types are exposed?
All this information is necessary for anyone to use or implement the API for the desired need.
=> Watch Out The Simple Postman Training Series Here.
Postman provides an easy to use documentation methodology and for basic documentation, it is as simple as clicking a button through the Postman collection and you can get public URL for your API documentation.
Table of Contents:
Creating API Documentation In Postman
Documentation Features
The salient features of the Postman documentation generator include:
- It supports markdown syntax. Markdown is generic documentation syntax, that you should’ve usually noticed on any Github project. It allows making styling and text formatting more familiar and easier.
- No specific syntax/requirements for creating documentation. The request and collection info is utilized in the best way to generate documentation.
- It can be published to a public URL or to a custom domain (for enterprise users).
- Generates code snippets for making calls to the API in different languages like C#, PHP, Ruby, Python, Node, etc.
Creating Documentation
The Postman document generator refers to the collection, folder & individual request description and collates them while creating or generating documentation for the collection.
It makes use of various request parameters like Headers, Query string parameters, Form parameters and indicates the use of these values in the request documentation.
Here is a Video Tutorial:
Let’s create a basic collection with 3 requests using the same test API as our other articles. We will add some information to the collection description as well as to the individual requests and also create some example requests and responses, which will also be captured while creating the documentation.
Follow the below steps for adding basic info about the requests and then creating the documentation.
#1) Create a collection with 3 requests i.e. Register User, Login User and Get User (Refer here for request payloads and API URLs).
#2) Now let’s add some info in markdown format to the collection. Markdown is a standard format that’s used for almost all documentation in Github (For more information about markdown refer here).
We’ll add some info to the collection description in the markdown format as below.
To preview how the markdown looks like, refer to the open-source web portal here.
#3) Now we will add the descriptions to individual requests in the collection. Similar to the collection, the markdown format is supported for request descriptions as well (For more detailed information on markdown guide, refer here).
Let’s see a sample of one of the requests for Register User endpoint (The same can be applied to other requests as well).
Markdown Text:
API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code
Markdown Preview:
#4) For all the API endpoints, let’s capture or save an example that would be used by the documentation generator.
An example is nothing but a sample request-response for the API request into consideration. Saving the response as an example enables the documentation generator to capture it as a part of the documentation itself.
To save an example, hit the “Send” button to execute the request and on the response tab, click Save Response -> Save as Example.
Once the example is saved, it gets persisted to the collection and can be accessed anytime in the future through an Examples link in the request builder.
#5) Once all the above information is added, let’s see how to create a documentation preview.
Open the collection options and click “Publish Docs”.
Note: An important thing to note here is that only registered users with Postman will be able to use the Publish docs feature on Postman. The registration is free but needs to be done through your email account. There are other capabilities/features like sharing collections and workspaces, creating monitors, etc. , that gets added to the registered accounts.
#6) Once “Publish Docs” is executed, a browser tab is opened with the Postman collection details (internally Postman hosts this collection to their own servers as well in addition to the user’s local file system).
Click on “Preview” to view the documentation before it’s being published.
“Publish Collection” link will publish the documentation to a publicly accessible URL. It’s generally not recommended to publish APIs having sensitive authorization information to publish to the public URL. Such APIs can be published using custom domains with enterprise accounts of the Postman.
#7) Let’s see how the documentation preview looks. Clicking “Preview Documentation” opens the documentation in a preview mode that’s hosted on Postman’s servers. Let’s see what different details are captured in the documentation (As we configured at different places. For example, collection description, request description & examples).
In the above 2 screenshots, you can see that all the information that was added to the collection and request descriptions are captured in a markdown styled way in the documentation preview.
Also, the documentation by default provides language bindings as highlighted and that makes it a lot easier for someone wanting directly to make the API request in the listed language.
#8) It also allows you to perform very basic styling modifications like changing the background color, changing the background and foreground color of the header templates, etc. But overall, the default view itself is sufficient to publish a really good set of documentation capturing a lot of important details about the API.
Conclusion
In this tutorial, we walked through the API documentation support provided by Postman, using which we can create a good looking, styled documentation with minimal effort.
It also allows lots of good templates and user-defined styling that could be applied to the generated docs and allows publishing documentation to a public URL as well.
For private API endpoints, there is also a provision to publish documentation to a custom domain that could be configured for the enterprise accounts or users.
Further reading =>> How to published Pact Contract to Pact Broker
=> Visit Here To Learn Postman From Scratch.