Guys, In this tutorial I’ll introduce you with an opensource tool that can definitely help you to create awesome API documentation!
Well, If you are writing REST API and exposing them using HTTP/JSON then there is a good chance you are using Postman to test the debug, test, and create a collection. Most of the time while working with a team you need to send the documentation to others like the android and iOS teams. Often we share the Postman collection in JSON format with handwritten documentation describing the API.
To avoid writing the documentation myself, back in 2018, I wrote a command-line tool that can generate HTML and Markdown documentation easily. Of course, there were other tools. Most probably out of interest and lacking proper tools I wrote the application myself.
To create documentation while writing APIs collection in Postman you need to provide the required information, that’s it. Let’s see how can we create the API doc.
First of all, you need to install the tool on your computer. For Mac, Linux you can install the application using the command below:
curl https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -o install.sh && sudo chmod +x install.sh && sudo ./install.sh
For windows, download the binary from here: https://github.com/thedevsaddam/docgen
If everything okay then you’ll see something like this:
Now export your Postman collection and save it.
To create an HTML documentation use the command below:
docgen build -i input-postman-collection.json -o ~/Downloads/index.html
If you need Markdown documentation then use the command:
docgen build -i input-postman-collection.json -o ~/Downloads/index.md -m
Docgen comes with a live server where you can preview your API doc without storing it. Sometimes it assists you to see what will be the final output.
For more information regarding the tool visit this page https://github.com/thedevsaddam/docgen
Hope this will help you. If you find the tutorial and the docgen helpful then don’t forget to share it with your developer friends. Thank you!