I have been into Backend development for most of my development experience — be it either Java , Node or NestJS. Documentation is always an important aspect which many developers tend to ignore.

While it’s important to implement the API the correct way , it’s also important to document it in a way that can be understood by the consumers of your API.

I understand that developer find documentation boring and I was one among them several years back :-) .

Documentation is a love letter that you write to your future self. — Damian Conway

For most of my early days and even today, Swagger is one of the ways but it does have a learning curve. Postman tool is what I have been using lately for testing REST APIs and in these years, Postman has evolved and have added bunch of features including Documentation.

Documenting using Postman is very simple and you can just create your collections , add APIs (with name, description) and can quickly publish documentation by right clicking and clicking on publish. For this post, you don’t need to publish. Just follow the below steps:

1. Export the Postman collection

Click on the 3 dots (…) against your collection and select ‘Export’. Select the recommended version , directory and submit.

2. Install docgen

docgen (https://github.com/thedevsaddam/docgen) is a tool (MIT license) that helps to transform the postman collections into formats like HTML and Markdown.

On Mac , you can follow the below steps:

curl https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -o install.sh \  
&& sudo chmod +x install.sh \  
&& sudo ./install.sh \  
&& rm install.sh

On windows, Download the library from here

3. Generate HTML and Markdown files from Postman collection exported in step 1

For HTML: docgen build -i <path_to_postman_collection> -o <file_name.html>

For Markdown: docgen build -i <path_to_postman_collection> -o <file_name.md> -m

4.Use the generated files

If you have named the output file as index.html , then you could simply put it in public folder of your API or at a path which is been called from the base route.

HTML Output

Markdown Output

This is one of the easiest way we could get REST API documentation done. It has some limitation, but it’s easy to use and just few clicks and a command away.

Just one thing that’s missing and would be great to have is the ability to specify environment details so that one could directly invoke the API as we can in Swagger.

Clap, share, comment, give me feedback. I’d love to hear your thoughts!
Happy Learning.