一、为什么要用 Swagger
Swagger 是一款自动生成接口文档的工具，开发人员需要根据规范定义接口。Python 中可以使用 Flask-restx 编写接口，而 Flask-restx 集成了 Swagger，可以直接通过 Swagger 生成接口文档。
二、如何使用 Swagger
1、定义 namespace
from flask import Flask
from flask_restx import Resource, Api, Namespace
app = Flask(__name__)
api = Api(app)
# 以下是使用Swagger规范定义接口的范例
# 1、定义 namespace（不同的路由可以定义不同的 namespace ）
user_ns = Namespace("user", description = 'user interface')
teacher_ns = Namespace("teacher", description = 'teacher interface')
# 2、使用预先定义的 namespace 添加子路由（tlf：一定要注意，这里是子路由哈）
# 将 @api.route('/user') 改写为 @user_ns.route('')
@user_ns.route('')
# @api.route('/user')
# 定义类，继承自 Resource
class User(Resource):
def get(self):
return {"code":0, "msg":"user, get success"}
def post(self):
return {"code": 0, "msg": "user, post success"}
def put(self):
return {"code": 0, "msg": "user, put success"}
def delete(self):
return {"code": 0, "msg": "user, delete success"}
# 2、使用预先定义的 namespace 添加子路由（tlf：一定要注意，这里是子路由哈，可以通过更改子路由然后观察运行效果来加深对子路由的理解）
# 将 @api.route('/user') 改写为 @user_ns.route('')
@teacher_ns.route('')
# @api.route('/teacher')
# 定义类，继承自 Resource
class Teacher(Resource):
def get(self):
return {"code":0, "msg":"teacher, get success"}
def post(self):
return {"code": 0, "msg": "teacher, post success"}
def put(self):
return {"code": 0, "msg": "teacher, put success"}
def delete(self):
return {"code": 0, "msg": "teacher, delete success"}
# 3、通过 api实例 将预先定义的 namespace 与 路由绑定
api.add_namespace(user_ns, '/user')
api.add_namespace(teacher_ns, '/teacher')
if __name__ == '__main__':
app.run(debug=True)
启动服务后，首页运行效果如下：
观察可知，该界面上显示了两个命名空间，分别是 user 和 teacher，与代码中定义的 namespace 完全一致。
展开每个命名空间，效果如下：
观察可知，每个命名空间对应的请求与代码中定义的接口完全一致。
2、在 flask-restx 中配置使用 Swagger
- 方法一：使用 @api.doc() 或者 @namespace.doc()装饰请求方法
eg： @api.doc(params) = {‘id’:‘input an ID’} - 方法二 【推荐】：使用 parser = api.parser() 结合 @api.expect(parser) 装饰器实现入参的校验和传入
未完待续…