软件测试|测试平台后端开发Flask框架-集成Swagger文档

介绍

• 接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后，编写接口文档更是重中之重。但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致，接口文档不规范，不及时更新等问题。

• 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格式同时存在

更多技术文章