Skip to content

Latest commit

 

History

History
86 lines (65 loc) · 3.18 KB

README.md

File metadata and controls

86 lines (65 loc) · 3.18 KB
Raw

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 Screenshot

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

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

    Screenshot

  • 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]

    Screenshot

  • 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

    Screenshot

  • 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

Sample HTML

Shout outs

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