Quels outils sont disponibles pour produire automatiquement la documentation d'une API REST écrite en Flask? [fermé]

Je cherche un moyen rapide de produire automatiquement des documents D'API REST à partir d'une API REST Flask que j'ai écrite. Est-ce que quelqu'un connaît des outils qui peuvent le faire et comment je baliserais le code?

25
demandé sur Martin Charlesworth 2013-01-12 20:24:48

3 réponses

Je vous recommande Sphinx , vous ajoutez votre documentation en tant que __doc__ et le module autodoc de Sphinx générera les documents pour vous ( docs.python.org utilise également Sphinx). Le balisage est reST, similaire à Markdown.

Par exemple:

@app.route('/download/<int:id>')
def download_id(id):
    '''This downloads a certain image specified by *id*'''
    return ...
20
répondu dav1d 2013-01-12 17:19:12

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 Flacon 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 statique nécessaire). Vous pouvez également obtenir toute la description de votre API dans JSON et l'analyser autrement.

17
répondu Clément Renaud 2014-11-17 14:55:09

Il existe une extension Flask: flask-autodoc pour la documentation automatique spécialement pour l'analyse de la règle de route des points de terminaison. Vous pouvez ajouter doc décorateur pour spécifier les Api que vous souhaitez 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:

entrez la description de l'image ici

6
répondu Cody 2014-04-16 08:44:32