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 :
