Documenting Flask Endpoint using Flask-Autodoc - GeeksforGeeks

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.
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. 
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 : 
Python Flask
Python
Writing code in comment?
Please use ide.geeksforgeeks.org,
generate link and share the link here.
How to Install PIP on Windows ?
How To Convert Python Dictionary To JSON?
How to drop one or multiple columns in Pandas Dataframe
Check if element exists in list in Python
Selecting rows in pandas DataFrame based on conditions
Python | os.path.join() method
Defaultdict in Python
Create a directory in Python
Python | Get unique values from a list
Python | Pandas dataframe.groupby()