flask-apidoc

Write API document when you coding, Test your API when you press last word immediately

Installation

​ $sudo pip install flask_doc

Useage

We suppose there's a Flask project in /var/www/app

1. command line

$cd /var/www/app
$fkapidoc manager.py app

This will generate all docstring in view functions to a markdown string print on screen, or you can save it to a file

$fkapidoc manager.py app > doc.md

If you don't need generate all view functions (return html not api), you can add an external parameter to set filters.

We suppose you there's a blueprint in project like below:

api = Blueprint('api', __name__, template_folder='templates', url_prefix='/api')

It contains all API view functions, we'd like to only generate documentation in the blueprint.

$fkapidoc manager.py app api. > doc.md

We can generate multi blueprint, just use "," to split.

$fkapidoc manager.py app api.,xxx.,yyy. > doc.md

2. Embedded in project

first step: import:

from flask_doc import Generator

second step: init generator

generator = Generator(app)

or use filter

generator = Generator(app, filters=["api."])

put line after in the last file before start server

generator.prepare()

then, when you start server, open

open: http://domain/api-doc

It will show you a web page contains API specification, Toc Index and Test Fly client

Click the paper plane will show you a form to invoke api, you can run it and see what happened immediately.

Formatting the doc_string

The query-string and form-data is not declear in function declearation and decorators, so we use a flat file format to declear it in doc_string

Here's an example:

def do_some_thing(resource_id):
    """
    #idx:3
    an example view function

    && query_string_key | false | int | a query-string parameter

    @@ form_key | true | string | a form-data parameter

    :param resource_id: resource_id
    :type resource_id:int
    :return:
    if success {rs=true}
    if faild   {rs=false, error=错误原因}
    :rtype:
    """

Show index :

#idx:number

Declear the sort index of api specification, this is not required

url pattern parameter :

:param resource_id: an key of resource_id
:type resource_id:int

this part can generate by PyCharm, it declear the description and the value type

form-data :

@@ form_key | required | value type | description

query-string :

&& query_key | required | value type | description

return value :

:return:
if success {rs=true}
if faild   {rs=false, error=resean of error}

all lines below ":return:" will declear what will return, just description, you can write what ever you like here

return type :

:rtype:

this generated by PyCharm, we don't need it actually.