pm2md

Convert a Postman collection to markdown documentation.

sample result

Template-driven. You can customize the output by editing a template. See the "custom templates" section below for more details.

download

3 choices for how to download:

• download a zipped executable file, unzip it, and run the app with ./pm2md --help
• go install github.com/wheelercj/pm2md@latest and then pm2md --help
• install from source following the instructions below

install from source

These steps require Go to be installed.

1. Choose one of the source code download options here and unzip the folder (or use git clone).
2. Open a terminal in the new folder.
3. Run go build to create an executable file.
4. Run go install to install the executable file. If you get an error message, you may need to edit your PATH environment variable.
5. Run the app with pm2md --help.

command examples

• pm2md collection.json documentation.md reads collection.json and saves markdown to documentation.md.
• pm2md collection.json reads collection.json and saves markdown to a new file with a unique name based on the collection's name. This will NEVER replace an existing file.
• pm2md collection.json --statuses=200 does the same as the previous example but does not include any sample responses except those with a status code of 200.
• pm2md collection.json --statuses=200-299,400-499 does not include any sample responses except those with a status code within the ranges 200-299 and 400-499 (inclusive).
• pm2md collection.json - reads collection.json and returns markdown to stdout.
• pm2md - - receives JSON from stdin and returns markdown to stdout, such as with cat collection.json | pm2md - -.
• pm2md - out.md receives JSON from stdin and saves markdown to out.md.

custom templates

You can customize the output by editing a template.

• pm2md --get-default creates a new file of the default template as a starting point for customization.
• pm2md --get-minimal creates a new file of a minimal template.
• pm2md api.json --template=custom.tmpl reads api.json and formats text using a custom template file named custom.tmpl. The result is saved into a new file with a unique name.
• pm2md test api.json custom.tmpl expected.md tests whether your custom template's output matches your expected result, and gives a helpful error message if it doesn't.

In a template, you can use the functions in the FuncMap in func_map.go. Sometimes it's helpful to look at the JSON exported from Postman to know what variables are available. pm2md adds a "level" integer property to each Postman item and response (folders, endpoints, and responses). These template docs might also be helpful:

• the template package — Go's standard library
• How To Use Templates in Go — DigitalOcean

tips

Any descriptions and examples you want to add to pm2md's output can usually be added in Postman. pm2md can then take those and automatically put them in the result for you. For example, after clicking "Send" in Postman, a "Save as Example" button appears so you can save a sample request and response. Also, there are many places in Postman to add descriptions to things, including collections, folders, requests, and more.

To add a description to a request, click the documentation button near the top-right corner:

Here's how to export a collection from Postman (choose the v2.1 export option):

developer resources

• intro to Go
• JSON and Go — The Go Blog
• the embed package — Go's standard library
• spf13/cobra
• GoReleaser
• GoReleaser Action
• how to create a custom terminal command
• Command Line Interface Guidelines by Prasad et al.