How to Generate API Documentation with Docgen Using a Postman Collection

Postman is a popular API development and testing tool that enables developers to design, test, and document APIs. It provides a user-friendly interface for making HTTP requests, supports various authentication methods, and allows users to create and manage API collections, automate tests, and generate API documentation.

DocGen seamlessly converts your Postman collection into well-structured HTML or Markdown documentation. In this article, we will explore a quick way to create API documentation from Postman Collection using Docgen.

Why use Docgen for documentation?

Docgen saves you time by automatically generating user-friendly documentation in your chosen format (e.g., HTML or Markdown) directly from your Postman collection file. This is beneficial if you want an out-of-the-box and quick documentation solution for your application. It is good to note that while Docgen streamlines documentation, its versatility and advanced capabilities may fall short compared to other API documentation tools such as Swagger.

Prerequisites

1. A postman collection you want to document

2. Command line or terminal.

3. Basic knowledge of command line usage. If you're new to the CLI, you can check out this beginner's guide from Freecodecamp.

If you meet these prerequisites, you're all set. Let's dive in!

Step 1: Organize Your Collection

Before you can generate documentation, you need to have a well-structured Postman collection. This collection should include all the requests, endpoints, parameters, and examples needed to showcase your API. Make sure you have added descriptions and explanations where necessary to ensure clarity.

Step 2: Export your Postman collection to your local machine

The Postman collection provides the source material for generating documentation with DocGen. It's essential to save it in the repository you're working on (where your API is located), ensuring easy access.

Step 3: Install Docgen

For Mac and Linux users: To install Docgen, run the following commands in your terminal:

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

And to uninstall Docgen, use this command:

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

These commands download, install, and uninstall Docgen as needed, simplifying the management of this tool on your system.

For Windows Users: To install Docgen, download the binary from https://github.com/thedevsaddam/docgen/releases/download/v3.3.0/windows_amd64.exe and save it in your working repository where your API is located (both postman collection and binary file are together).

Step 4: Generate Documentation

To create documentation, execute the following command in your terminal:

docgen build -i postman-collection-name.json -o index.html

Here, -i designate the input; please provide the name of your Postman collection file. Meanwhile, -o signifies the output; enter the desired file name, for example, index.html. This command will generate the documentation for your API.

For Windows users, it's recommended to execute this command in Command Prompt rather than other terminals. Use the binary file name instead of "docgen," as shown in the example:

windows_amd64 build -i postman-collection-name.json -o index.html

Following these steps, you'll successfully generate the index.html documentation file.

In this guide, you will explore how to quickly create API documentation from your Postman collection using Docgen. By organizing your collection, exporting it, installing Docgen, and generating documentation, you can save time and offer user-friendly documentation for your APIs. If you encounter any difficulties or require additional clarification during this process, feel free to reach out on X (formerly Twitter) @mekwunyeclinton or drop a comment below. Your feedback and questions are always welcome.

Thanks for reading.