34

我正在寻找一种从我编写的 Flask REST API 自动生成 REST API 文档的快速方法。有谁知道可以做到这一点的工具以及我将如何标记代码？

4

3 回答 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 回答