Python 有哪些工具可用于为用 Flask 编写的 REST API 自动生成文档？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/14295322/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
What tools are available to auto-produce documentation for a REST API written in Flask?
提问by Martin Charlesworth
I'm looking for a quick way to auto produce REST API docs from a Flask REST API I've written. Does anyone know of tools that can do this and how I would markup the code?
我正在寻找一种从我编写的 Flask REST API 自动生成 REST API 文档的快速方法。有谁知道可以做到这一点的工具以及我将如何标记代码？
采纳答案by dav1d
I would recommend you Sphinx, you add your documentation as __doc__and the autodocmodule of Sphinx will generate the docs for you (docs.python.orgalso uses Sphinx). The markup is reStructuredText, similiar to Markdown (if you prefer Markdown, you can use pdoc).
我会推荐你Sphinx，你添加你的文档，Sphinx__doc__的autodoc模块会为你生成文档（docs.python.org也使用 Sphinx）。标记是reStructuredText，类似于Markdown （如果你更喜欢 Markdown，你可以使用pdoc）。
e.g.:
例如：
@app.route('/download/<int:id>')
def download_id(id):
'''This downloads a certain image specified by *id*'''
return ...
回答by Cody
There is a Flask extension: flask-autodocfor auto documentation specially parsing endpoint route rule. You can add docdecorator to specify which APIs you want to doc:
有一个 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
The simple html documentation page is like this:
简单的html文档页面是这样的：
回答by Clément Renaud
I really like Swaggerbecause it allows to generate an API documentation by just adding a few decorators and comments into your code. There is a Flask Swaggeravailable.
我真的很喜欢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):
...
Then you can see your methods and notes in an html interface just by visiting /api/v1/spec (it serves needed static automatically). You can also just get all your API description in JSON and parse it otherwise.
然后你可以通过访问 /api/v1/spec （它自动提供需要的静态）在 html 界面中看到你的方法和注释。您也可以仅以 JSON 格式获取所有 API 描述，然后以其他方式对其进行解析。
