Developers sometimes spend a 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 API documentation in 20 minutes? Yes, it is possible and we are going to learn how to do that now.

Apparently, Postman is the most commonly used REST Client for testing API endpoints, but most people don't realize that it can be used to generate well-formatted documentation. In this tutorial, we are going to expose a simple trick on 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 existing API endpoints.

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.

Create a new collection or add to the existing one.

How to add your existing requests to a collection.

• On your existing request window hold command + S keys
• Click on create a 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. Collection tabHenceforth, 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 copied 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 a description. Click on the edit to add the request descriptionClick on the edit option to add a description to the request. When you click on the edit link, a new pop up modal opens for you to add your descriptions. Add a description to the request.After adding your description hit the save button. All you have to do next is go to any of the requests in your collection folder and add a description to them.

All that remains is publishing your documentation on Postman server. Now go to your collection and go to the options menu. Now go to the publish docs and see the magic for yourself. If you notice any 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 and time in documenting APIs. If you notice any typographical error please feel free to drop a comment. Happy coding.

Reference https://medium.com/@olotintemitope/how-to-generate-your-api-documentation-in-20-minutes-4e0072f08b94