介绍
-
接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后，编写接口文档更是重中之重。但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致，接口文档不规范，不及时更新等问题。
-
Swagger 可以完美的解决上述问题， Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，它支持自动生成接口文档界面，支持在界面上测试API接口等功能
namespace(命名空间)的使用
from flask import Flask
from flask_restx import Resource, Api, Namespace
app = Flask(__name__)
api = Api(app)
# 定义命名空间
demo = Namespace("demo", description='demo学习')
case = Namespace("case", description='case练习')
# @api.route('/case')
# 定义子路由,如果没有的话，传空字符串即可
@case.route("")
class Case(Resource):
# 定义restful 风格的方法
def get(self):
return {'code': 0, 'msg': 'get success'}
def post(self):
return {'code': 0, 'msg': 'post success'}
def put(self):
return {'code': 0, 'msg': 'put success'}
def delete(self):
return {'code': 0, 'msg': 'delete success'}
# @api.route('/demo')
@demo.route("")
class Demo(Resource):
# 定义restful 风格的方法
def get(self):
return {'code': 0, 'msg': 'get success'}
def post(self):
return {'code': 0, 'msg': 'post success'}
def put(self):
return {'code': 0, 'msg': 'put success'}
def delete(self):
return {'code': 0, 'msg': 'delete success'}
# 添加命名空间，并指定空间路径
api.add_namespace(demo, '/demo')
api.add_namespace(case, '/case')
if __name__ == '__main__':
app.run(debug=True)
效果展示：
Swagger接口文档配置
方式一：
使用@api.doc()或者@namespace.doc()装饰请求方法
from flask import Flask
from flask_restx import Resource, Api, Namespace, fields
app = Flask(__name__)
# 自定义版本号
api = Api(app, version="2.0")
# 定义命名空间
demo = Namespace("demo", description='demo学习')
@demo.route("")
class Demo(Resource):
# 传递参数
@demo.doc(params={'id': 'ID'})
def get(self):
return {'code': 0, 'msg': 'get success'}
# 定义body数据
post_model = api.model('PostModel', {
# 定义post请求对应的数据
# description描述信息
# required约束是否为必填项
'name': fields.String(description='The name', required=True),
# enum 枚举型，只允许在给定的值里选择，限制不是很强，选C也可以请求成功
'type': fields.String(description='The object type', enum=['A', 'B']),
# int类型，min属性指定最小值
'age': fields.Integer(min=0),
})
@demo.doc(body=post_model)
def post(self):
return {'code': 0, 'msg': 'post success'}
方式二【推荐】：
使用parser = api.parser()配合@api.expect（parser）或者@namespace.expect（parser）装饰器实现入参的校验和传入
-
api.parser() ：解析器
-
方法二当请求参数类型不匹配或出现其他问题时，会有明显的提示，比方法一更直观
-
required 是否为必填项
from flask import Flask, request
from flask_restx import Resource, Api, Namespace, fields
from log_utils import logger
app = Flask(__name__)
# 自定义版本号
api = Api(app, version="2.0")
case = Namespace("case", description='case练习')
# @api.route('/case')
# 定义子路由,如果没有的话，传空字符串即可
@case.route("")
class Case(Resource):
# 定义parser解析器对象
get_parser = api.parser()
# 添加测试参数
# location的值对应request对象的一些属性
get_parser.add_argument('id', type=int, location='args')
@api.expect(get_parser)
def get(self):
logger.info(f'request.args ==>{request.args}')
return {'code': 0, 'msg': 'get success'}
api.add_namespace(case, '/case')
常用的关键字参数
-
处理get请求，一般来说用args，即 location=‘args’
-
处理post请求，一般来说用json，file，form
-
choice枚举类型的location=‘args’
from flask import Flask, request
from flask_restx import Resource, Api, Namespace, fields
from log_utils import logger
app = Flask(__name__)
# 自定义版本号
api = Api(app, version="2.0")
case = Namespace("case", description='case练习')
@case.route("")
class Case(Resource):
# 定义parser解析器对象
get_parser = api.parser()
# 添加测试参数
# location的值对应request对象的一些属性
get_parser.add_argument('id', type=int, location='args', required=True)
get_parser.add_argument('name', type=str, location='args')
@api.expect(get_parser)
def get(self):
logger.info(f'request.args ==>{request.args}')
return {'code': 0, 'msg': 'get success'}
post_parser = api.parser()
# post_parser.add_argument('username', type=str, help='username', location='form')
# post_parser.add_argument('password', type=str, help='password', location='form')
# post_parser.add_argument('id', type=int, location='json', required=True)
# post_parser.add_argument('name', type=str, location='json', required=True)
# post_parser.add_argument('file', type=FileStorage, location='files', required=True)
post_parser.add_argument('choice', choices=("1", "2"), location='args')
@api.expect(post_parser)
def post(self):
# logger.info(f"request.form ==>{request.form}")
# logger.info(f"request.files ==>{request.files}")
# choice格式
logger.info(f"request.json ==>{request.args}")
# logger.info(f"request.json ==>{request.json}")
return {'code': 0, 'msg': 'post success'}
api.add_namespace(case, '/case')
注意：json格式和file格式不能同时存在，也不能和form格式同时存在