Une API sans documentation, ça n'existe pas. Enfin si, mais personne ne l'utilisera. Écrire la doc à la main dans un Word ou un Wiki ? L'enfer. Elle sera périmée dans 2 jours.
La solution : La documentation générée automatiquement depuis le code. Le standard : OpenAPI (ex-Swagger).
Il existe plusieurs extensions. Mes préférées :
- APIFairy (Très moderne, s'intègre parfaitement avec Marshmallow).
- Flasgger (Plus ancien, utilise des docstrings).
Exemple avec APIFairy
pip install apifairy
from apifairy import APIFairy, body, response
apifairy = APIFairy(app)
class UserSchema(ma.Schema):
username = ma.fields.String()
email = ma.fields.Email()
@app.route('/api/users', methods=['POST'])
@body(UserSchema) # Documente que cette route attend un body correspondant au schéma
@response(UserSchema, 201) # Documente qu'elle renvoie un User et un 201
def create_user(args):
# 'args' contient déjà les données validées et désérialisées !
return args
Si tu vas sur http://localhost:5000/docs, tu verras une interface magnifique (Swagger UI) qui décrit toutes tes routes, les paramètres attendus, et te permet même de tester l'API en direct.
C'est la classe internationale. 😎