目录
- Flask-Docs
- 特性
- 安装
- 使用
- 配置
- 如何书写 markdown 格式文档
- Api demo
- 完整代码
- Flask-RESTful Api demo
- flask.views.MethodView Api demo
- 装饰器 @ApiDoc.change_doc
- 调试器
Flask-Docs
影响我写文档的原因可能是代码和文档分离，有时候写完代码会忘记补文档，而且不能及时查看，使用 Flask-Docs 可以解决我的问题，这个插件可以根据代码注释生成文档页面，代码注释改动文档可以及时更新，而且支持离线文档下载，支持在线调试。
Flask-Docs Flask Api 文档自动生成插件
特性
- 根据代码注释自动生成文档
- 支持离线 markdown 文档下载
- 支持 Flask-RESTful
- 支持 Flask-RESTX
- 支持 flask.views.MethodView
- 支持在线调试
链接 https://github.com/kwkwc/flas...
安装
pip3 install Flask-Docs
使用
from flask import Flask
from flask_docs import ApiDoc
app = Flask(__name__)
ApiDoc(
app,
title="Flask-Docs自动生成Api文档安装使用教程",
version="1.0.0",
description="A simple app API",
)
配置
# 使用 CDN # app.config["API_DOC_CDN"] = True # 禁用文档页面 # app.config["API_DOC_ENABLE"] = False # SHA256 加密的授权密码，例如这里是 admin # echo -n admin | shasum -a 256 # app.config["API_DOC_PASSWORD_SHA2"] = "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918" # 允许显示的方法 # app.config["API_DOC_METHODS_LIST"] = ["GET", "POST", "PUT", "DELETE", "PATCH"] # 自定义 url_prefix # app.config["API_DOC_URL_PREFIX"] = "/docs/api" # 需要排除的 RESTful Api 类名 # app.config["API_DOC_RESTFUL_EXCLUDE"] = ["Todo"] # 需要显示的 Api 蓝图名称 # app.config["API_DOC_MEMBER"] = ["api", "platform"] # 需要排除的子成员 Api 函数名称 # app.config["API_DOC_MEMBER_SUB_EXCLUDE"] = ["delete_data"]
如何书写 markdown 格式文档
@@@在注释结尾用 "@@@" 包含 markdown 格式文档@@@
查看文档页面
http://127.0.0.1/docs/api/
Api demo
@api.route("/add_data", methods=["POST"])
def add_data():
"""Add some data
@@@
### args
| args | nullable | request type | type | remarks |
|-------|----------|--------------|------|----------|
| title | false | body | str | blog title |
| name | false | body | str | person's name |
### request
```json
{"title": "xxx", "name": "xxx"}
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return jsonify({"api": "add data"})
@api.route("/delete_data", methods=["GET"])
def delete_data():
"""Delete some data
@@@
### args
| args | nullable | request type | type | remarks |
|--------|----------|--------------|------|--------------|
| id | true | query | str | blog id |
| name | false | query | str | person's name |
### request
```
http://127.0.0.1:5000/api/delete_data?name=xxx
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return jsonify({"api": "delete data"})
@platform.route("/get_something", methods=["GET"])
def get_something():
"""Get some data
@@@
### request example
```python
import requests
url="http://127.0.0.1:5000/platform/get_something"
try:
print(requests.get(url).text)
except:
pass
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return jsonify({"platform": "get something"})
完整代码
from flask import Blueprint, Flask, jsonify
from flask_docs import ApiDoc
app = Flask(__name__)
app.config["API_DOC_MEMBER"] =javascript ["api", "platform"]
ApiDoc(
app,
title="Flask-Docs自动生成Api文档安装使用教程",
version="1.0.0",
description="A simple app API",
)
api = Blueprint("api", __name__)
platform = Blueprint("platform", __name__)
@api.route("/add_data", methods=["POST"])
def add_data():
"""Add some data
@@@
### args
| args | nullable | request type | type | remarks |
php |-------|----------|--------------|------|----------|
| title | false | body | str | blog title |
| name | false | body | str | person's name |
### request
```json
{"title": "xxx", "name": "xxx"}
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return jsonify({"api": "add data"})
@api.route("/delete_data", methods=["GET"])
def delete_data():
"""Delete some data
@@@
### args
| args | nullable | request type | type | remarks |
|--------|----------|--------------|------|--------------|
| id | true | query | str | blog id |
| name | false | query | str | person's name |
### request
```
http://127.0.0.1:5000/api/delete_data?name=xxx
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return jsonify({"api": "delete data"})
@platform.route("/get_something", methods=["GET"])
def get_something():
"""Get some data
@@@
### request example
```python
import requests
url="http://127.0.0.1:5000/platform/get_something"
try:
print(requests.get(url).text)
except:
pass
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
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)
Flask-RESTful Api demo
from flask import Flask
from flask_restful import Api, Resource
from flask_docs import ApiDoc
app = Flask(__name__)
restful_api = Api(app)
ApiDoc(
app,
title="Flask-Docs自动生成Api文档安装使用教程",
version="1.0.0",
description="A simple app restful API",
)
class Todo(Resource):
"""Manage todo"""
def post(self):
"""Add todo
@@@
### description
> Add todo
### args
| args | nullable | request type | type | remarks |
|-------|----------|--------------|------|----------|
| name | false | body | str | todo name |
| type | false | body | str | todo type |
### request
```json
{"name": "xx", "type": "code"}
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return {"todo": "post todo"}
def get(self):
"""Get todo
@@@
### description
> Get todo
### args
| args | nullable | request type | type | remarks |
|-------|----------|--------------|------|----------|
| name | false | querandroidy | str | todo name |
| type | true | query | str | todo type |
### request
```
http://127.0.0.1:5000/todo?name=xxx&type=code
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return {"todo": "get todo"}
restful_api.add_resource(Todo, "/todo")
if __name__ == "__main__":
apythonpp.run(host="0.0.0.0", port=5000, debug=True)
flask.views.MethodView Api demo
目前只支持与类名相同的 url_rule
from flask.views import MethodView
class TodoList(MethodView):
"""Manage todolist"""
def put(self):
"""Change the data
"""
return jsonify({"toDOS": "put todolist"})
def delete(self):
"""Delete the data
"""
return jsonify({"todos": "delete todolist"})
app.add_url_rule("/todolist/", view_func=TodoList.as_view("todolist"))
装饰器 @ApiDoc.change_doc
复用注释
from flask_docs import ApiDoc
return_json_str = '{"code": xxxx, "msg": "xxx", "data": null}'
@api.route("/add_data", methods=["POST"])
@ApiDoc.change_doc({"return_json": return_json_str})
def add_data():
"""Add some data
@@@
### return
```json
return_json
```
@@@
"""
return jsonify({"api": "add data"})
@api.route("/delete_data", methods=["GET"])
@ApiDoc.change_doc({"return_json": return_json_str})
def delete_data():
"""Delete some data
return_json
"""
return jsonify({"api": "delete data"})
调试器
以上就是Flask-Docs自动生成Api文档安装使用教程的详细内容，更多关于pythonFlask-Docs生成Api文档的资料请关注编程客栈(www.devze.com)其它相关文章！
加载中,请稍侯......
精彩评论