我正在寻找一种从我编写的 Flask REST API 自动生成 REST API 文档的快速方法。有谁知道可以做到这一点的工具以及我将如何标记代码?
问问题
28097 次
3 回答
24
我会推荐你 Sphinx,你添加你的文档,Sphinx__doc__
的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 ...
于 2013-01-12T17:19:12.730 回答
22
我真的很喜欢Swagger,因为它允许通过在代码中添加一些装饰器和注释来生成 API 文档。有一个Flask 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):
...
然后,您只需访问 /api/v1/spec 即可在 html 界面中查看您的方法和注释(它会自动提供所需的静态)。您也可以只获取 JSON 格式的所有 API 描述,然后进行解析。
于 2014-11-17T14:55:09.723 回答
6
有一个 Flask 扩展:flask-autodoc用于自动文档,专门解析端点路由规则。您可以添加doc
装饰器来指定要记录的 API:
@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 文档页面是这样的:
于 2014-04-16T08:44:32.130 回答