Easy Swag
La norme de documentation Swagger/OpenApi offre un moyen simple d’aider les développeurs qui utilisent votre API REST. En Python, il existe plusieurs modules conçus pour vous aider à produire cette documentation. Bien qu’ils vous facilitent la vie, il y a toujours moyen d’aller plus loin.
J'ai travaillé sur le back-end d'un projet web qui utilisait le serveur web Flask et le système de sérialisation Marshmallow. Il existe plusieurs modules Python pour aider à générer la documentation Swagger, mais il est toujours possible de simplifier encore plus la tâche. C’est pourquoi j’ai écrit easy swag.
Description
Le module easy swag est construit autour du module “flask_apispec” et le module “marshmallow”. Il contient deux fonctions et un décorateur :
set_error_schema(): définit le schéma Marshmallow à utiliser comme rapport d’erreur pour toutes les API REST.register_with_swagger_docs(): enregistre toute la documentation swagger/OpenApi qui a été déclarée avec l’application Flask.swag(): le décorateur qui prend les schémas d’entrée et de sortie, la chaîne de documentation, le tag et le code d’état HTTP retourné. Il génère la documentation appropriée.
Exemple
Voici quelques extraits d’une application de démonstration Flask.
La première étape est l’enregistrement du schéma Marshmallow utilisé pour signaler les erreurs dans l’API REST. Dans notre exemple, nous avons déclaré une classe de schéma ExpectedError.
Python
# Set the error schema used in function
# and documented in swagger doc.
set_error_schema(schemas.ExpectedError, ‘400, 403’)
La deuxième étape consiste à décorer les routes Flask avec le décorateur de easy swag. Par exemple, voici la route /dogs. Il utilise le décorateur @swag, en lui passant le schéma de sortie, la documentation et un tag. Comme cette route ne prend pas de données en entrée et utilise le statut de succès standard, il n’est pas nécessaire de les préciser. Comme vous pouvez le constater, il suffit donc d’une seule ligne de code pour chaque route.
Python
@app.route(‘/dogs’, methods=[‘GET’])
@swag(output=schemas.Dogs, doc=‘Retrieve all dogs’, tag=‘dogs’)
def dogs_get_handler():
# ... your implementation code would be here ...
Le décorateur supporte ces éléments :
input: le schéma de Marshmallow d’entrée, décrivant le JSON reçu.output: le schéma Marshmallow de sortie, décrivant le JSON retourné.doc: la documentation décrivant l’API REST.tag: le tag utilisé pour regrouper les routes similaires entre elles.success: le code d’état retourné en cas de succès.
La dernière étape est d’enregistrer toute la documentation qui a été déclarée. Un simple appel de fonction est tout ce dont on a besoin. Il faut lui fournir l’application Flask et le nom de votre API REST. En option, il peut également prendre la version de votre API REST et l’URL sous laquelle servir la documentation au format standard de OpenApi.
Python
register_with_swagger_docs(app, title = ‘web-example-app’)
Disponibilité
Vous pouvez trouver le module easy-swag dans une application de démonstration Flask que j'ai rendu disponible sur GitHub dans le cadre de mon repo resto.
Le module easy-swag est contenu dans un seul fichier : src/flask-app/easy_swag.py.
