In this tutorial, I’ll introduce you to an open-source tool that makes creating amazing API documentation effortless!
If you’re working with REST APIs and exposing them through HTTP/JSON, there’s a good chance you’re already using Postman to test, debug, and manage collections. When collaborating with teams, especially Android or iOS developers, you often need to share your API documentation. This typically involves sharing the Postman collection in JSON format along with manually written documentation to describe the API.
To eliminate the hassle of manual documentation, I built a command-line tool back in 2018 that automatically generates API documentation in HTML and Markdown formats. While there were other tools available at the time, I wanted something more tailored to my workflow, so I decided to create my own solution.
With this tool, generating API documentation from your Postman collection is simple and efficient. All you need to do is provide the necessary information, and the tool takes care of the rest. Let’s dive into how you can use Docgen to create your API documentation effortlessly.
Step 1: Installing Docgen
First, you’ll need to install Docgen on your computer. If you’re using macOS or Linux, you can install it by running the following command in your terminal:
curl https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -o install.sh && sudo chmod +x install.sh && sudo ./install.sh
For Windows users, you can download the binary directly from the Docgen GitHub repository.
After completing the installation, you should see a confirmation message indicating that the installation was successful.
Step 2: Export Your Postman Collection
Next, export your Postman collection and save it as a JSON file. This file will act as the input for generating your API documentation.
Step 3: Generate HTML or Markdown Documentation
To generate HTML documentation, use the following command:
docgen build -i input-postman-collection.json -o ~/Downloads/index.html
If you’d rather generate documentation in Markdown format, use the following command:
docgen build -i input-postman-collection.json -o ~/Downloads/index.md -m
Preview Your Documentation with Docgen’s Live Server
Docgen also includes a live server feature that lets you preview your API documentation in real-time, without the need to save the output file. This is especially useful when you want to quickly review the final result.
For more detailed instructions and additional features, visit the official Docgen GitHub page: https://github.com/thedevsaddam/docgen.
With Docgen, you can save time and streamline your API documentation process, making collaboration with your team more efficient!
This tool has been extremely helpful in my own projects, and I hope it proves useful to you as well. Give it a try, and feel free to let me know what you think!