哪些工具可用于为 Flask 编写的 REST API 自动生成文档？ [关闭]

Posted 2023-02-23

【中文标题】哪些工具可用于为 Flask 编写的 REST API 自动生成文档？ [关闭]

【英文标题】：What tools are available to auto-produce documentation for a REST API written in Flask? [closed]

【发布时间】：2012-12-27 01:09:10

【问题描述】：

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

【参考方案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，因为它允许通过在代码中添加一些装饰器和 cmets 来生成 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 描述，然后进行解析。

【讨论】：

Swagger 链接已损坏。 swagger.io/tools/swagger-ui

这个问题的重要性与这个社区急于解决问题的态度形成鲜明对比，这就是这里需要解决的问题的完美例子。这是一个很好的问题，我正在寻找答案，我想请作者扩展这个问题，但我不能。这个问题不是 MWE，也不清楚 @swagger 是什么。

【参考方案3】：

有一个 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文档页面是这样的：

【讨论】：

我意识到这是一种观点，但我会警告人们远离 flask-autodoc。扩展确实不完整。它开始时很棒，并且设置了您期望的方式，但最终结果乏善可陈。大多数人会因为 sphinx 而放弃它，并且会在 flask-autodoc 上浪费几个小时。

要是我在 30 分钟前看到这个就好了……+1

您能否详细说明为什么 flask-autodoc 不完整？我快速浏览了它的文档，我比 Flask-RESTplus 更喜欢它。

@imolit flask-autodoc 在使用蓝图时失败

我今天找到了这个帖子，这个解决方案看起来很有希望。不幸的是，它不再维护，但我在这里找到了一个维护良好的分支：github.com/jwg4/flask-selfdoc