Skip to content

Latest commit

 

History

History
114 lines (96 loc) · 2.16 KB

README.md

File metadata and controls

114 lines (96 loc) · 2.16 KB
Raw

api-documenter the easiest way

JSON to HTML

api-documenter is a simple script that allows you to generate beautiful HTML documentation from a JSON description file easily.

Demo

You can find a nice demo here.

Requirements

  • Python >= 3
  • python-slugify >= 1.2.6
  • dominate >= 2.3.5

Credits

Library Autor License Website
dominate Tom Flanagan and Jake Wharton LGPL v3.0 https://github.com/Knio/dominate
slugify Val Neekman MIT https://github.com/un33k/python-slugify

Installation

pip3 install python-slugify
chmod +x install.sh
./install.sh
apidoc --help

Description structure

Note: all the keys should be double quoted and the values should be replaced. See the example for more information.

API (root)

{
    title: string,
    description: string | string[],
    host: string,
    requests: Request[],
    statusCodes: StatusCode[]
}

Request

{
    title: string,
    method: string,
    description: string | string[],
    url: string,
    parameters: Parameter[],
    examples: Example[]
}

Parameter

{
    name: string,
    type: string,
    optional: boolean,
    description: string
}

Example (request)

{
    description: string | string[],
    type: 'request',
    protocol: string = 'HTTP/1.1',
    headers: Header[],
    body: string | string[]
}

Example (response)

{
    description: string,
    type: 'response',
    protocol: string = 'HTTP/1.1',
    status: string,
    headers: Header[],
    body: string[]
}

Header

{
    key: string,
    value: string
}

StatusCode

{
    code: number,
    reason: string,
    meaning: string
}

License (GPLv3)

api-documenter  Copyright (C) 2018  Ivan Avalos <[email protected]>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.