影响我写文档的原因可能是代码和文档分离，有时候写完代码会忘记补文档，而且不能及时查看，使用 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)