Documenting Flask Endpoint using Flask-Autodoc

Last Updated : 04 Jul, 2021

Documentation of endpoints is an essential task in web development and being able to apply it in different frameworks is always a utility. This article discusses how endpoints in Flask can be decorated to generate good documentation of them using the Flask-Autodoc module. This module provides the following features –

Helps to document endpoints of application based upon routes, function arguments, and docstrings.
Renders on the terminal as well as on HTML templates.
Customed grouping and templating provided.

Installation

To install this module type the below command in the terminal.

pip install flask-autodoc

After installation, Autodoc class needs to imported and initialized with the application context. And routes need to be defined.

Functions Used

doc() : All the routes with this wrapper only will be documented.
html() : Generates documentation in HTML format.
generate() : Generates documentation in Non-HTML format.

Note:

The possible error that can occur while using the flask-autodoc is that –

ModuleNotFoundError: No module named 'flask.ext'

To remove this error open the __init__.py file of the flask_autodoc module and change the

from flask.ext.autodoc.autodoc import Autodoc
to
from flask_autodoc.autodoc import Autodoc

Generating documentation in HTML format

Python3

from flask import Flask, render_template 
  
app = Flask(__name__) 
from flask_autodoc.autodoc import Autodoc 
  
auto = Autodoc(app) 
  
# GET API 
@app.route('/') 
def index(): 
    return render_template('index.html') 
  
  
# POST API 
@auto.doc() 
@app.route('/add', methods = ['POST']) 
def post_data(): 
    return render_template('form.html') 
  
  
# GET API with path param 
@app.route('/gfg/<int:page>') 
@auto.doc() 
def gfg(page): 
    return render_template('gfg.html', page=page) 
  
# This route generates HTML of documentation 
@app.route('/documentation') 
def documentation(): 
    return auto.html() 
  
if __name__ == '__main__': 
    app.run()

After running the server, route to /documentation, exact documentation of routes with wrapper .doc() will be displayed.
Output :

Example 2 : Printing documentation on stdout.

This can be achieved using generate()

Python3

from flask import Flask, render_template 
  
app = Flask(__name__) 
from flask_autodoc.autodoc import Autodoc 
  
auto = Autodoc(app) 
  
# GET API 
@app.route('/') 
def index(): 
    return render_template('index.html') 
  
# POST API 
@auto.doc() 
@app.route('/add', methods = ['POST']) 
def post_data(): 
    return render_template('form.html') 
  
# GET API with path param 
@app.route('/gfg/<int:page>') 
@auto.doc() 
def gfg(page): 
    return render_template('gfg.html', page=page) 
  
# This route generates documentation in list  
# of rules 
@app.route('/documentation') 
def documentation(): 
    return str(auto.generate())

Output :

Explanation: List of rules, with certain parameters.

methods : Method allowed (ie [‘GET’, ‘POST’])
rule : Relative Url Structure (ie ‘/gfg/int:page’)
endpoint: Function name (ie ‘gfg’)
doc : Docstring of the function if provided
args : Function arguments if provided ( e.g page )
defaults : Defaults values for the arguments.

Example 3 : Working with Custom Templating

Apart from the generic template, a custom template with a custom template and other jinja compatible tags can be passed onto HTML for documenting better by passing in auto.html() function.

Python3

from flask import Flask, render_template 
  
app = Flask(__name__) 
from flask_autodoc.autodoc import Autodoc 
  
auto = Autodoc(app) 
  
# GET API 
@app.route('/') 
@auto.doc() 
def index(): 
    return render_template('index.html') 
  
  
# GET API with path param 
@app.route('/gfg/<int:page>') 
@auto.doc() 
def gfg(page): 
    return render_template('gfg.html', page=page) 
  
  
# This route generates documentation in list of rules 
# in custom html 
@app.route('/documentation') 
def documentation(): 
    return auto.html(template='custom_autodoc.html',  
                     title='Custom Gfg Flask AutoDoc', 
                     author='Manjeet Singh',) 
  
if __name__ == '__main__': 
    app.run()

Output :

Example 4: Working with groups

Separate documentation sets can be constructed to keep logics/endpoints abstracted from certain sets according to use cases, or depending upon product requirements of groupings. Each route can be part of 1 or more groups by passing “groups” as list.

Python3

from flask import Flask, render_template 
  
app = Flask(__name__) 
from flask_autodoc.autodoc import Autodoc 
  
auto = Autodoc(app) 
  
  
@app.route('/') 
@auto.doc(groups=['red']) 
def index(): 
    return render_template('index.html') 
  
  
@app.route('/gfg/<int:page>') 
@auto.doc(groups=['green']) 
def gfg(page): 
    return render_template('gfg.html', page=page) 
  
  
@app.route('/gfg-red-green') 
@auto.doc(groups=['green', 'red']) 
def gfg_all(page): 
    return render_template('gfg-all.html', page=page) 
  
  
@app.route('/gfg-blue-hidden') 
@auto.doc(groups=['blue']) 
def gfg_blue(page): 
    return render_template('gfg-blue.html', page=page) 
  
  
# generating red grouped urls 
@app.route('/red') 
def red(): 
    return auto.html(groups='red') 
  
  
# generating blue grouped urls 
@app.route('/blue') 
def blue(): 
    return auto.html(groups='blue') 
  
  
# generating green grouped urls 
@app.route('/green') 
def green(): 
    return auto.html(groups='green') 
  
  
if __name__ == '__main__': 
    app.run() 