dzhibas/rest-api-doc

Generates restful API documentation out of annotated php source files

RESTful api documentation build tool

script to build restful api documentation out of annotated PHP (for now) code. Output example you can find here

annotation example:

/**
 * @route /v1/modulename/authentication
 * @method POST
 * @ingroup modulename
 *
 * authentication service example
 *
 * HTTP response code tells about status of login:
 *
 * - 202: Request Accepted
 * - 401: Invalid username/password
 * - 403: Request Denied
 * - 503: Service Unavailable
 *
 * @example input
 *
 * POST /v1/modulename/authentication HTTP/1.1
 * Content-Type: application/json; charset=utf-8
 *
 * {
 *  "username": "demousername",
 *  "passwrod": "demopassword",
 * }
 *
 * @example output
 *
 * {
 *  "message":"Request Accepted",
 *  "id":386
 * }
 *
 * @jsonparam username extranet username required
 * @jsonparam password extranet password required
 *
 * @returns json
 */

Installation

pip install restapidoc

Usage

$ restapidoc --help

Help

usage: restapidoc [-h] [-c] [-d DIR] [--filter FILTER] [-o OUTPUT]

optional arguments:
  -h, --help            show this help message and exit
  -c, --coverage        ouputs into stdin documentation coverage
  -d DIR, --dir DIR     folder in which we need look for documentation
                        annotation. default: test_src_folder/
  --filter FILTER       gob filter in which files to search. default:
                        *Controler*.php
  -o OUTPUT, --output OUTPUT
                        output filename. default: documentation.html

rest-api-doc's Issues

Move expressions to library per language

Move expresions to library and seperate them per language. So you can provide language you want and it will parse specific language docstrings

Load module description from local folder

check for local module description file lets say in yaml format and load it if its existing.