使用 Flask-Docs 自动生成 Api 文档

影响我写文档的原因可能是代码和文档分离，有时候写完代码会忘记补文档，而且不能及时查看，使用 Flask-Docs 可以解决我的问题，这个插件可以根据代码注释生成文档页面，代码注释改动文档可以及时更新，而且支持离线文档下载。

Flask-Docs
Flask Api 文档自动生成插件

特性
根据代码注释自动生成文档
支持 Flask-RESTful
支持离线 markdown 文档下载
安装
pip install Flask-Docs

使用
from flask import Flask
from flask_docs import ApiDoc

app = Flask(__name__)

# 本地加载
# app.config['API_DOC_CDN'] = False

# 禁用文档页面
# app.config['API_DOC_ENABLE'] = False

# 需要显示文档的 Api
app.config['API_DOC_MEMBER'] = ['api', 'platform']

# 需要排除的 RESTful Api 文档
app.config['RESTFUL_API_DOC_EXCLUDE'] = []

ApiDoc(app)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
如何书写 markdown 格式文档
@@@
在注释结尾用 “@@@” 包含 markdown 格式文档
@@@

查看文档页面
http://127.0.0.1/docs/api

Api demo
@api.route('/add_data', methods=['POST'])
def add_data():
"""Add some data

Add some data in this routing

Args:
pass

Returns:
pass
"""
return jsonify({'api': 'add data'})
1
2
3
4
5
6
7
8
9
10
11
12
13

@api.route('/del_data', methods=['POST'])
def del_data():
"""Del some data

@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| title | false | string | blog title |
| name | true | string | person's name |

#### return
- ##### json
> {"msg": "success", "code": 200}
@@@
"""
return jsonify({'api': 'del data'})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@platform.route('/get_something', methods=['GET'])
def get_something():
"""
@@@
#### example
```
import requests
url='http://127.0.0.1:5000/api/get_something'
try:
print requests.get(url).text
except:
pass
```
@@@
"""
return jsonify({'platform': 'get something'})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

完整代码
#!/usr/bin/env python
# -*- coding:utf-8 -*-

from flask import Flask, render_template, jsonify, Blueprint
from flask_docs import ApiDoc

app = Flask(__name__)

# Local loading
# app.config['API_DOC_CDN'] = False

# Disable document pages
# app.config['API_DOC_ENABLE'] = False

# Api Document needs to be displayed
app.config['API_DOC_MEMBER'] = ['api', 'platform']

ApiDoc(app)

api = Blueprint('api', __name__)
platform = Blueprint('platform', __name__)

@api.route('/add_data', methods=['POST'])
def add_data():
"""Add some data

Add some data in this routing

Args:
pass

Returns:
pass
"""
return jsonify({'api': 'add data'})

@api.route('/del_data', methods=['POST'])
def del_data():
"""Del some data

@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| title | false | string | blog title |
| name | true | string | person's name |

#### return
- ##### json
> {"msg": "success", "code": 200}
@@@
"""
return jsonify({'api': 'del data'})

@platform.route('/get_something', methods=['GET'])
def get_something():
"""
@@@
#### example
```
import requests
url='http://127.0.0.1:5000/api/get_something'
try:
print requests.get(url).text
except:
pass
```
@@@
"""
return jsonify({'platform': 'get something'})

app.register_blueprint(api, url_prefix='/api')
app.register_blueprint(platform, url_prefix='/platform')

if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000, debug=True)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
Flask-RESTful Api demo
from flask_restful import Resource, Api

class TodoList(Resource):
"""Manage todolist"""

def post(self):
"""Submission of data

Args:
pass

Returns:
pass

"""
return {'todos': 'post todolist'}

def get(self):
"""
@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| id | false | int | todo id |

#### return
- ##### json
> {...}
@@@
"""
return {'todos': 'get todolist'}

restful_api.add_resource(TodoList, '/todolist')
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

完整代码
#!/usr/bin/env python
# -*- coding:utf-8 -*-

from flask import Flask
from flask_restful import Resource, Api
from flask_docs import ApiDoc

app = Flask(__name__)

# Local loading
# app.config['API_DOC_CDN'] = False

# Disable document pages
# app.config['API_DOC_ENABLE'] = False

# RESTful Api documents to be excluded
app.config['RESTFUL_API_DOC_EXCLUDE'] = []

restful_api = Api(app)
ApiDoc(app)

class TodoList(Resource):
"""Manage todolist"""

def post(self):
"""Submission of data

Args:
pass

Returns:
pass

"""
return {'todos': 'post todolist'}

def get(self):
"""
@@@
#### args

| args | nullable | type | remark |
|--------|--------|--------|--------|
| id | false | int | todo id |

#### return
- ##### json
> {...}
@@@
"""
return {'todos': 'get todolist'}

restful_api.add_resource(TodoList, '/todolist')

if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000, debug=True)