How to generate your api documentation with Postman in 20 minutes
Developers sometimes spend couple of weeks building an API and maybe another week writing the documentation, and this can be time consuming. The question is, is it possible to generate an API documentation in 20 minutes? Yes it is possible and I’m going to show you how.
Apparently, Postman is the most commonly used application for testing API endpoints, but most people don’t realize that Postman can be used to generate a well formatted documentation. In this tutorial I’m going to show you how to leverage Postman to ease the stress of generating documentation.
I will not be covering how to build an API in this tutorial; I want to assume that you already have an existing API.
Shall we begin the magic?
Creating a documentation
Leveraging your existing requests to generate the documentation
If you have already tested your endpoints on Postman then congratulations, all you have to do now is to go back to the requests and add them to a collection.
What’s a POSTMAN collection
Postman collection allows you to save your requests in such a way that they can be reused and shared anytime. It also allows you to group your requests so that each api resource can act like a folder where you can save similar endpoints.
Let’s add our existing requests to a collection.
How to add your existing requests to a collection.
- On your existing request window hold command + S keys
- Click on create collection
- Add your preferred name
- Hit save button
After completing the above steps, you now have a collection which you can further add your requests. Immediately you create a new collection it appears on the collection tab.
Henceforth, all you need to do is adding your new or existing requests to the collection.
What does Postman automate for you ?
- Headers (it helps you add all your headers to the documentation).
- Request body (The JSON Request sent to your endpoints is copy over to your documentation.
- Your requests with their HTTP verbs ( post, get, put, patch e.t.c) are automatically added for you.
What you have to do by yourself?
Adding comments to the endpoints is all you have to do for yourself . You will need to go to your collection folder and go to any request you wish to add description to.
Click on the edit option to add description to the request. When you click on the edit link, a new pop up opens for you to add your descriptions.
After adding your description hit the save button. All you have to do next is to go to any of the requests in your collection folder and add description to them.
All that remains is publishing your documentation on Postman server. Now go to our collection and go to option menu.
Now go to the publish docs and see the magic for yourself.
The screenshot above is what it generates for you. Boom! we’re done.
If you notice typo in your generated documentation, you can always go back to the collection and make edits but don’t forget to publish the docs again.
I hope this help save a lot of lives.
If you notice any errata please feel free to drop a comment.