postman-doc-gen

Generate HTML API documentation from a postman collection. You can use this tool to auto-generate the documentation and host it alongside your API's as detailed here.

Usage

• Download the latest release of the executable from here.

• Open a new terminal and call the executable with the parameter -h to see the help info

• To generate documentation using a postman collection, use the following command -

  ./postman_doc_gen [path/to/collection] -o [path/to/output/folder] 

  

• To apply environment values to the examples, use the following command -

  ./postman_doc_gen [path/to/collection] -o [path/to/output/folder] -e [path/to/environment/json]

  

• To enable download links to the collection and environment files, use the following command -

  ./postman_doc_gen [path/to/collection] -o [path/to/output/folder] -e [path/to/environment/json] -d true

  

• The output folder should now show the following -

  1. index.html - this is the html documentation generated from the collection
  2. css - this is the css folder consisting of the necessary css files
  3. js - this is the javascript folder consisting of the required js files
  4. collection json - if the download option was enabled, the collection json is also copied
  5. environment json - if the download option was enabled and an env file provided, the env json is also copied

To build locally

• Clone the repository
• Download Python 3.7
• Create a virtual env (recommended but optional)

  python -m venv venv
  source ./venv/bin/activate

• pip install the dependencies from the requirements file

  pip install -r requirements.txt

• run the code

  python postman_doc_gen.py [path/to/collection] -o [path/to/output/folder] 

• to create a new executable

  pyinstaller postman_doc_gen.spec postman_doc_gen.py

  Note: If you get the following error when running the pyinstaller command

  OSError: Python library not found: libpython3.7.dylib, .Python, libpython3.7m.dylib, Python, Python3 

  then you need to re-install python on your machine with enable-shard & recreate the virtual environment

  env PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.7.14 

Sample HTML Documentation

A video of the sample html document generated using the collection and environment json files present in the example folder

Shout outs

The following tools/repos have been instrumental in building this tool

• Jinja
• PyInstaller
• Giphy Capture
• Bleach