Flask-Autodoc 0.1.2

Flask-Autodoc
=============

Flask-Autodoc是一个Flask扩展，它根据路由、函数参数和文档字符串自动为您创建端点文档。

[](https://travis-ci.org/acoomans/flask-autodoc)
[](https://pypi.python.org/pypi/Flask-Autodoc)
[](https://pypi.python.org/pypi/Flask-Autodoc)


## 要求

Flask-Autodoc与Python 2和3兼容；它只依赖于Flask。

## 安装

要安装Flask-Autodoc，请运行pip

pip install flask-autodoc

或克隆此目录并运行setup

python setup.py install

## 使用

通过导入并初始化Flask-Autodoc开始使用

from flask import Flask
from flask.ext.autodoc import Autodoc

app = Flask(__name__)
auto = Autodoc(app)

默认情况下，Flask-Autodoc 只会文档化那些显式使用 _doc_ 装饰器装饰的路由。

@app.route('/user/')
@auto.doc()
def show_user(id)
return user_from_database(id)

要生成文档，请使用 _html()_ 方法

@app.route('/documentation')
def documentation()
return auto.html()

## 自定义文档

要获取不渲染 HTML 的文档

@app.route('/documentation')
def documentation()
return auto.generate()

文档将以规则列表的形式返回，其中每个规则都是一个包含以下内容的字典：

- methods: 允许的方法集合（例如 ['GET', 'POST']）
- rule: 相对 URL（例如 '/user/'）
- endpoint: 函数名称（例如 'show_user'）
- doc: 函数的文档字符串
- args: 函数参数
- defaults: 参数的默认值

## 自定义模板

要为您的文档使用自定义模板，请将 _template_ 参数传递给 _html_ 方法。这将使用 Flask _templates_ 目录中的模板。

除了 _group_、_groups_ 和 _template_ 之外的其他参数将传递给模板

auto.html(

template='custom_documentation.html'

title='My Documentation',
author='John Doe',
)


_title_ 和 _author_ 将在模板中可用

<!-- templates/custom_documentation.html -->
...
{% if title is defined %}
{{title}}
{% endif %}
...

## 文档集合

端点可以被分组到不同的文档集合中。例如，可以向第三方开发者展示一些端点，而为主要开发者提供完整的文档。

要将端点分配到某个组，请将组名作为 _doc_ 装饰器的参数传递

@app.route('/user/')
@auto.doc('public')
def show_user(id)

要将端点分配到多个组，请将组名列表作为 _groups_ 参数传递给 _doc_

@app.route('/user/')
@auto.doc(groups=['public','private'])
def show_user(id)

要生成特定组的文档，请将组名传递给 _html_ 或 _generate_ 方法

auto.html('public')
auto.html(groups=['public','private'])
auto.generate('public')

## 示例

“examples” 目录中的应用程序是一个博客的 API

- “simple” 是一个简单的应用程序
- “factory” 使用蓝图

运行方法：

python simple/blog.py

然后连接到 [/doc/public](http://127.0.0.1:5000/doc/public) 和 [/doc/private](http://127.0.0.1:5000/doc/private) 来查看公共和私有文档。

## 屏幕截图