Je cherche un moyen rapide de produire automatiquement REST API docs à partir d'un Flask REST API que j'ai écrit) Est-ce que quelqu'un connaît les outils qui peuvent le faire et comment je baliserais le code?
Je vous recommanderais Sphinx , vous ajoutez votre documentation comme __doc__
et le module autodoc
de Sphinx générera les documents pour vous ( docs.python.org utilise également Sphinx). Le balisage est reStructuredText , similaire à Markdown (si vous préférez Markdown, vous pouvez utiliser pdoc ).
par exemple.:
@app.route('/download/<int:id>')
def download_id(id):
'''This downloads a certain image specified by *id*'''
return ...
J'aime vraiment Swagger car il permet de générer une documentation API en ajoutant simplement quelques décorateurs et commentaires dans votre code. Il y a un Flask Swagger disponible.
from flask import Flask
from flask.ext.restful import Api
from flask_restful_swagger import swagger
app = Flask(__name__)
api = swagger.docs(Api(app), apiVersion='1', api_spec_url="/api/v1/spec")
class Unicorn(Resource):
"Describing unicorns"
@swagger.operation(
notes='some really good notes'
)
def get(self, todo_id):
...
Ensuite, vous pouvez voir vos méthodes et notes dans une interface html simplement en visitant/api/v1/spec (il sert automatiquement la statique nécessaire). Vous pouvez également simplement obtenir toute la description de votre API en JSON et l'analyser autrement.
Il y a une extension Flask: flask-autodoc pour la documentation automatique spécialement en analysant la règle de route du point de terminaison. Vous pouvez ajouter doc
décorateur pour spécifier les API que vous voulez au doc:
@app.route('/doc')
@auto.doc()
def documentation():
'''
return API documentation page
'''
return auto.html()
@app.route('/')
@auto.doc()
def welcome():
'''
Welcome API
'''
commit_hash = subprocess.check_output(["git", "rev-parse", "HEAD"])
commit_msg = subprocess.check_output(["git", "log", "-1", "--format=%s"])
date_time = subprocess.check_output(["git", "log", "-1", "--format=%cd"])
return "Welcome to VM Service Server. <br/>" \
"The last commit: %s<br/>Date: %s, <br>Hash: %s" % \
(commit_msg, date_time, commit_hash), 200
La page de documentation html simple est comme ceci: