Postman is a popular API testing tool used by developers to streamline the process of testing APIs. One of the useful features of Postman is its ability to create collections, which are a set of requests grouped together for easy management and sharing. While Postman allows sharing collections with others, sometimes it becomes necessary to convert these collections into a more readable and presentable format, like HTML.
Postmanerator is a powerful tool that helps convert Postman collections into beautiful HTML documentation. In this article, we will explore how to use Postmanerator in combination with Docker to automate the conversion process and generate comprehensive HTML documentation for your API.
Before we proceed, ensure you have the following prerequisites:
- Docker installed and configured on your system.
- A Postman collection file (in .json format) that you want to convert to HTML.
Dockerfile for Postmanerator: Here’s Dockerfile that sets up the environment required to run Postmanerator:
# Use the official Golang image as the base image
FROM golang:latest
# Set the working directory to /app
WORKDIR /app
# Clone the Postmanerator repository
RUN git clone https://github.com/aubm/postmanerator.git
# Change the working directory to /app/postmanerator
WORKDIR /app/postmanerator
# Build Postmanerator from the source
RUN go build
# Add the Postman collection file to the container
COPY your_collection.json /app/postmanerator/your_collection.json
# Set the entrypoint to run Postmanerator
ENTRYPOINT ["/app/postmanerator/postmanerator"]
Step 1:
Prepare the Dockerfile Create a new file named “Dockerfile” and copy the provided content into it. This Dockerfile sets up a Go environment, clones the Postmanerator repository, builds the binary, and adds your Postman collection file to the container.
Step 2:
Build the Docker Image Navigate to the directory where you saved the Dockerfile and the Postman collection file. Open a terminal or command prompt and execute the following command to build the Docker image:
docker build -t postmanerator .
Step 3:
Generate HTML Documentation Once the Docker image is built, you can now run the container to convert the Postman collection to HTML. Use the following command
docker run -v "$(pwd)/output:/app/postmanerator/output" postmanerator -output="/app/postmanerator/output/index.html" -collection="/app/postmanerator/your_collection.json"
Explanation:
- The docker run command executes the Docker container.
- The -v flag maps the container’s output directory to the host machine’s output directory. In this example, we used $(pwd)/output to map the current working directory’s “output” folder.
- The -output flag specifies the path and name of the output HTML file inside the container.
- The -collection flag specifies the path and name of your Postman collection JSON file inside the container.
Step 4:
View the HTML Documentation After running the Docker container, the HTML documentation will be generated inside the “output” folder on your host machine. Open the “index.html” file using a web browser to view the beautifully formatted documentation.
Converting Postman collections to HTML can be a valuable way to share API documentation with stakeholders and team members. By using Postmanerator and Docker, you can automate this process and generate HTML documentation effortlessly. The provided Dockerfile and step-by-step guide should help you get started quickly and efficiently create comprehensive API documentation for your projects.
Appendix:
You can also serve the HTML file over a web browser using the below docker configuration.
# Use a lightweight base image
FROM golang:1.17-alpine AS build
# Install Git
RUN apk add --no-cache git
# Install Postmanerator
RUN go get -u github.com/aubm/postmanerator
# Set the working directory
WORKDIR /app
# Copy the Postman collection JSON file into the container
COPY postman-collection.json /app/your-collection.json
# Generate the documentation
RUN postmanerator -collection /app/your-collection.json -output /app/documentation.html
# Use a smaller base image for the final image
FROM alpine:latest
# Copy the generated documentation from the build image
COPY --from=build /app/documentation.html /app/documentation.html
# Expose the port (optional - only if you want to run a simple web server)
EXPOSE 80
# Install a simple HTTP server to serve the documentation
RUN apk add --no-cache busybox-extras
# Start the HTTP server to serve the documentation
CMD ["httpd", "-f", "-h", "/app", "-p", "80"]
version: '1'
services:
docs:
build: .
volumes:
- ./output.html:/app/output.html
ports:
- 80:80