Documentación de Flask Endpoint usando Flask-Autodoc

La documentación de endpoints es una tarea fundamental en el desarrollo web y poder aplicarla en diferentes frameworks siempre es una utilidad. Este artículo analiza cómo se pueden decorar los puntos finales en Flask para generar una buena documentación de ellos utilizando el módulo Flask-Autodoc. Este módulo proporciona las siguientes características: 

• Ayuda a documentar los puntos finales de la aplicación en función de rutas, argumentos de función y strings de documentación.
• Se renderiza tanto en la terminal como en plantillas HTML.
• Se proporcionan plantillas y agrupaciones personalizadas.

Instalación

Para instalar este módulo, escriba el siguiente comando en la terminal.

pip install flask-autodoc

Después de la instalación, la clase Autodoc debe importarse e inicializarse con el contexto de la aplicación. Y las rutas necesitan ser definidas. 

Funciones utilizadas

• doc() : Solo se documentarán todas las rutas con este contenedor.
• html() : Genera documentación en formato HTML.
• generar() : genera documentación en formato no HTML.

Nota:

El posible error que puede ocurrir al usar el matraz-autodoc es que: 

ModuleNotFoundError: No module named 'flask.ext'

Para eliminar este error, abra el archivo __init__.py del módulo matraz_autodoc y cambie el 

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

Generación de documentación en formato HTML 

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

Después de ejecutar el servidor, ruta a /documentación, se mostrará la documentación exacta de las rutas con el contenedor .doc().
Producción :

Ejemplo 2: Impresión de documentación en stdout. 

Esto se puede lograr usando generar()

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

Producción : 

Explicación: Lista de reglas, con ciertos parámetros. 

• métodos : Método permitido (es decir, [‘GET’, ‘POST’])
• regla : estructura de URL relativa (es decir, ‘/gfg/int:page’)
• punto final : Nombre de la función (es decir, ‘gfg’)
• doc : Docstring de la función si se proporciona
• args : Argumentos de función si se proporcionan (p. ej., página)
• defaults : valores predeterminados para los argumentos.

Ejemplo 3: trabajar con plantillas personalizadas

Además de la plantilla genérica, una plantilla personalizada con una plantilla personalizada y otras etiquetas compatibles con jinja se pueden pasar a HTML para documentar mejor al pasar la función auto.html().

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

Producción : 

Ejemplo 4: Trabajar con grupos

Se pueden construir conjuntos de documentación separados para mantener las lógicas/puntos finales abstraídos de ciertos conjuntos según los casos de uso, o según los requisitos del producto de las agrupaciones. Cada ruta puede formar parte de 1 o más grupos pasando «grupos» como lista.

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

Producción :