Sto cercando un modo rapido per produrre automaticamente documenti API REST da un'API REST Flask che ho scritto. Qualcuno sa di strumenti che possono fare questo e come vorrei markup il codice?Quali strumenti sono disponibili per la documentazione di auto-produzione per un'API REST scritta in Flask?
ti consiglierei Sphinx, si aggiunge la documentazione come __doc__ e il modulo autodoc della Sfinge genererà la documentazione per voi (docs.python.org inoltre usa Sfinge). Il markup è reST, simile a Markdown.
es .:
@app.route('/download/<int:id>')
def download_id(id):
'''This downloads a certain image specified by *id*'''
return ...
C'è un'estensione Flask: flask-autodoc per la documentazione automatica appositamente parsing regola percorso endpoint. È possibile aggiungere doc decoratore per specificare che le API si desidera 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 semplice pagina di documentazione HTML è come questo:
Mi rendo conto che è una specie di opinione, ma metterei in guardia le persone dalla fiaschetta-autodoc. L'estensione è davvero incompleta. Si inizia alla grande, e si imposta come ti aspetteresti, ma il risultato finale è poco brillante. La maggior parte della gente lo abbandonerà per sfinge e avrà sprecato poche ore in fiasco-autodoc. – melchoir55
Se solo l'avessi visto 30 minuti fa ... +1 – Zeb
Potresti spiegare perché flask-autodoc è incompleto? Ho dato una rapida occhiata alla documentazione per questo, e mi è piaciuto molto più di, ad esempio, Flask-RESTplus. – imolit
mi piace Swagger perché permette di generare un'API documentazione semplicemente aggiungendo alcuni decoratori e commenti nel codice. C'è uno Flask Swagger disponibile.
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):
...
Poi si può vedere i vostri metodi e le note in un'interfaccia HTML semplicemente visitando/api/v1/spec (Serve necessario statica automaticamente). Puoi anche ottenere tutta la descrizione dell'API in JSON e analizzarla in altro modo.
C'è persino un modulo Sphinx chiamato sphinxcontrib.autohttp.flask (http://pythonhosted.org/sphinxcontrib-httpdomain/#module-sphinxcontrib.autohttp.flask). –