Я ищу быстрый способ автоматического создания документов API REST из API флагов REST, которые я написал. Кто-нибудь знает инструменты, которые могут это сделать, и как я буду разметки кода?
Какие инструменты доступны для автоматической подготовки документации для REST API, написанной в Flask?
Ответ 1
Я бы порекомендовал вам Sphinx, вы добавили свою документацию как __doc__
и модуль Sphinx для autodoc
сгенерирует для вас документы (docs.python.org также использует Sphinx). Разметка reStructuredText, похожая на Markdown (если вы предпочитаете Markdown, вы можете использовать pdoc).
например:
@app.route('/download/<int:id>')
def download_id(id):
'''This downloads a certain image specified by *id*'''
return ...
Ответ 2
Мне очень нравится Swagger, потому что он позволяет генерировать документацию API, просто добавив несколько декораторов и комментарии в ваш код. В наличии есть Колбаса Swagger.
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):
...
Затем вы можете увидеть свои методы и заметки в html-интерфейсе, просто зайдя в /api/v1/spec (он автоматически подает необходимую статическую информацию). Вы также можете просто получить все ваше описание API в формате JSON и проанализировать его в противном случае.
Ответ 3
Существует расширение фляшки: flask-autodoc для автоматической документации, специально разобравшего правила маршрута конечной точки. Вы можете добавить декоратор doc
, чтобы указать, какие API вы хотите использовать 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
Простая страница документации html выглядит следующим образом: