In this tutorial, I’ll introduce you to an open-source tool that can help you create awesome API documentation effortlessly!
If you’re working with REST APIs and exposing them through HTTP/JSON, chances are you’re already using Postman to test, debug, and manage collections. When collaborating with teams—especially with Android or iOS developers—you often need to share your API documentation. Typically, this involves sharing the Postman collection in JSON format along with handwritten documentation to describe the API.
To eliminate the need for manual documentation, I built a command-line tool back in 2018 that automatically generates HTML and Markdown API documentation. While other tools existed, I wanted something more tailored to my workflow, so I developed this tool myself.
With this tool, creating API documentation from your Postman collection is straightforward. You only need to provide the necessary information, and the tool handles the rest. Let’s dive into how you can generate your API documentation using Docgen.
Step 1: Installing Docgen
First, you’ll need to install Docgen on your computer. For macOS and Linux, use the following command:
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.
Once installed, you should see a confirmation screen indicating successful installation.
Step 2: Export Your Postman Collection
Next, export your Postman collection and save it as a JSON file. This collection will serve as the input for generating your API documentation.
Step 3: Generate HTML or Markdown Documentation
To create HTML documentation, use the following command:
docgen build -i input-postman-collection.json -o ~/Downloads/index.html
If you prefer to generate Markdown documentation, use this 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 allows you to preview your API documentation in real-time without saving the output file. This can be helpful when you want to quickly review the final output.
For more detailed instructions and features, visit the official Docgen GitHub page.
With Docgen, you can save time and streamline your API documentation process, making collaboration with your team more efficient!
This tool has been incredibly useful in my own projects, and I hope it can help you too. Give it a try, and let me know what you think!