软件测试学习笔记丨 Flask 框架 - 集成 Swagger 文档

2024-06-03
北京
本文字数：2728 字
阅读完需：约 9 分钟

本文转自测试人社区，原文链接：https://ceshiren.com/t/topic/23424

介绍

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后，编写接口文档更是重中之重。但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致，接口文档不规范，不及时更新等问题。
Swagger 可以完美的解决上述问题， Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，它支持自动生成接口文档界面，支持在界面上测试 API 接口等功能

namespace(命名空间)的使用

from flask import Flaskfrom 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 Flaskfrom 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, requestfrom 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, requestfrom 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')