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
docgen build -i <path_to_postman_collection> -o <file_name.html>
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.
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!