Skip to content
Related Articles

Related Articles

Documenting Flask Endpoint using Flask-Autodoc

View Discussion
Improve Article
Save Article
  • Difficulty Level : Easy
  • Last Updated : 04 Jul, 2021
View Discussion
Improve Article
Save Article

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()

Output : 


My Personal Notes arrow_drop_up
Recommended Articles
Page :

Start Your Coding Journey Now!