本文转自测试人社区,原文链接:https://ceshiren.com/t/topic/23424
介绍
- 接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后,编写接口文档更是重中之重。但是由于项目周期等原因后端人员经常出现无法及时更新,导致前端人员抱怨接口文档和实际情况不一致,接口文档不规范,不及时更新等问题。
- 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格式同时存在
推荐学习
【霍格沃兹测试开发】7天软件测试快速入门带你从零基础/转行/小白/就业/测试用例设计实战
【霍格沃兹测试开发】最新版!Web 自动化测试从入门到精通/ 电子商务产品实战/Selenium (上集)
【霍格沃兹测试开发】最新版!Web 自动化测试从入门到精通/ 电子商务产品实战/Selenium (下集)
【霍格沃兹测试开发】明星讲师精心打造最新Python 教程软件测试开发从业者必学(上集)
【霍格沃兹测试开发】明星讲师精心打造最新Python 教程软件测试开发从业者必学(下集)
【霍格沃兹测试开发】精品课合集/ 自动化测试/ 性能测试/ 精准测试/ 测试左移/ 测试右移/ 人工智能测试
【霍格沃兹测试开发】腾讯/ 百度/ 阿里/ 字节测试专家技术沙龙分享合集/ 精准化测试/ 流量回放/Diff
【霍格沃兹测试开发】Pytest 用例结构/ 编写规范 / 免费分享
【霍格沃兹测试开发】JMeter 实时性能监控平台/ 数据分析展示系统Grafana/Docker 安装
【霍格沃兹测试开发】接口自动化测试的场景有哪些?为什么要做接口自动化测试?如何一键生成测试报告?
【霍格沃兹测试开发】面试技巧指导/ 测试开发能力评级/1V1 模拟面试实战/ 冲刺年薪百万!
【霍格沃兹测试开发】腾讯软件测试能力评级标准/ 要评级表格的联系我
【霍格沃兹测试开发】Pytest 与Allure2 一键生成测试报告/ 测试用例断言/ 数据驱动/ 参数化
【霍格沃兹测试开发】App 功能测试实战快速入门/adb 常用命令/adb 压力测试
【霍格沃兹测试开发】阿里/ 百度/ 腾讯/ 滴滴/ 字节/ 一线大厂面试真题讲解,卷完拿高薪Offer !
【霍格沃兹测试开发】App自动化测试零基础快速入门/Appium/自动化用例录制/参数配置
【霍格沃兹测试开发】如何用Postman 做接口测试,从入门到实战/ 接口抓包(最新最全教程)
【霍格沃兹测试开发】6 小时轻松上手功能测试/ 软件测试工作流程/ 测试用例设计/Bug 管理
【霍格沃兹测试开发】零基础小白如何使用Postman ,从零到一做接口自动化测试/ 从零基础到进阶到实战
【霍格沃兹测试开发】建议收藏全国CCF 测试开发大赛Python 接口自动化测试赛前辅导 / 项目实战
更多软件测试开发视频教程点此
软件测试职业发展
零基础入门
测试必备编程篇
自动化测试
性能测试
测试管理
工程效能篇
面试求职篇
软件测试的面试宝典,内含一线互联网大厂面试真题、面试技巧、软件测试面试简历指导,免费领取!