SpringBoot整合knife4j(swagger)实现前后端分离可视化接口调试与接口测试
目录
- 1、为什么使用Knife4j
- 2、基本使用
- 2.1 pom
- 2.2 配置Knife4j分组
- 2.3 拦截器放行
- 2.4 实体类
- 2.5 SpringBoot整合基础使用
- 2.5.1 基础配置
- 2.5.2 Post(实体)请求
- 2.5.3 Get(实体)请求与响应参数
- 2.5.4 Header参数请求
- 2.5.5 非实体参数请求
- 2.5.6 全局参数配置
- 3、分组排序
- 4、接口排序
- 5、访问页面权限控制
- 6、生产环境屏蔽
- 7、多个Controller分组
1、为什么使用Knife4j
在前后端分离的开发模式下，后端人员开发完接口后，需要单独出一份文档，说明每个接口的作用以及接口的传入参数与响应参数；但是项目处于快速开发阶段时，就会出现文档更新不及时的情况，久而久之在对接接口时就会出现效率下降的情况，Knife4j提供一个可视化的UI界面，通过Knife4j只需要注解就可以向前端暴漏出所有的接口信息，便于前端对接以及对系统的测试。页面访问方式为：ip:prot/context-path/doc.html
2、基本使用
2.1 pom
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version>
</dependency>
2.2 配置Knife4j分组
创建配置文件：Knife4jConfig
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {/*** 创建一个Docket实例，指定controller包路径** @return*/@Bean(value = "test")public Docket test() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo())//分组名称.groupName("系统管理").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.project.test.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API").description("接口详细文档").contact(new Contact("开发者名称", null, "开发者邮箱")).version("1.0").build();}
}
2.3 拦截器放行
如果项目中配置了拦截器，那个会拦截Knife4j的请求的资源，需要进行放行处理，比如：
@Configuration
public class WebMvcRegistrationsConfig extends WebMvcConfigurationSupport {@Resourceprivate AuthenticationHandlerInterceptor authenticationHandlerInterceptor;@Overridepublic void addInterceptors(InterceptorRegistry registry) {// 无需拦截的接口集合List<String> ignorePath = new ArrayList<>();// knife4j(swagger)ignorePath.add("/swagger-resources/**");ignorePath.add("/doc.html");ignorePath.add("/v2/**");ignorePath.add("/webjars/**");ignorePath.add("/static/**");ignorePath.add("/templates/**");ignorePath.add("/error");//先拦截认证registry.addInterceptor(authenticationHandlerInterceptor).addPathPatterns("/**").excludePathPatterns(ignorePath);}@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}
2.4 实体类
创建一个实体类，通过knife4j提供的ApiModelProperty对字段添加描述
public class User{@ApiModelProperty("主键")private String id;@ApiModelProperty("名称")private String name;@ApiModelProperty("手机邮箱")private String mail;@ApiModelProperty("用户性别（0男 1女 2未知）")private Integer gender;@ApiModelProperty("头像") private String avatar;@ApiModelProperty("部门Id") private String deptId;
}
2.5 SpringBoot整合基础使用
2.5.1 基础配置
通过@Api注解，为当前Controller进行命名，通过@ApiOperation为Controller中的方法设置名称
@Api(tags = "用户管理")
@RestController
public class UserController {@ApiOperation(value = "基础测试", notes = "基础测试")@GetMapping("/test")public void test() {System.out.println("进入了test接口");}
}
访问测试：
访问地址为格式ip:prot/context-path/doc.html，比如：http://127.0.0.1:10008/demo/doc.html
调试测试：
在点击相应的接口名称后，就可以进入到调试页面，通过发送按钮发起接口请求；
2.5.2 Post(实体)请求
和传统的Post请求写法一致参数加上@RequestBody注解，通过@ApiOperation为接口命名
Controller：
@Api(tags = "用户管理")
@RestController
public class UserController {@ApiOperation(value = "新增数据", notes = "新增数据")@PostMapping("/add")public void insert(@RequestBody User user) {System.out.println("新增用户：" + user);}
}
文档页面：
调试页面：
结果：
2.5.3 Get(实体)请求与响应参数
对于Get请求时，我们可能会存在返回一个对象也可能是一个集合的情况，可以提供@ApiOperation注解的response方法设置响应参数，通过responseContainer=List设置返回的类型为集合，具体实现如下：
@Api(tags = "用户管理")
@ApiSort(10)
@RestController
@RequestMapping("user")
public class UserController {@ApiOperation(value = "查询列表", notes = "查询列表", response = UserParam.class, responseContainer = "List")@ApiOperationSupport(order = 1)@GetMappingpublic List<UserParam> listUser(BaseQueryParam param) {return new ArrayList<>();}@ApiOperation(value = "根据Id查询查询", notes = "根据Id查询", response = UserParam.class)@ApiOperationSupport(order = 2)@GetMapping("/{userId}")public UserParam getUserRole(@PathVariable("userId") String userId) {return new UserParam();}
}
文档说明文档：
调试页面：
可以看到Get请求的请求参数形式是以列表的形式进行呈现，而Post的请求参数是json形式
2.5.4 Header参数请求
在项目开发中，存在接口需要传入在header中传递token获取其他参数的情况，通过@ApiImplicitParam注解设置paramType = "header"，用法如下：
@Api(tags = "用户管理")
@RestController
@RequestMapping("user")
public class UserController {@ApiOperation(value = "根据Id查询", notes = "根据Id查询", response = UserParam.class)@ApiImplicitParam(name = "token", value = "token令牌", paramType = "header", required = true, dataType = "String")@GetMappingpublic UserParam getUserRole(HttpServletRequest request) {System.out.println("获取Header：" + request.getHeader("token"));return new UserParam();}}
效果：
2.5.5 非实体参数请求
对于传入请求参数，如果参数不对，可能不会进行实体类的封装，那么可以进行单独的参数配置，通过@ApiImplicitParam设置paramType = "path",如果是多个@ApiImplicitParam需要在外面加一个@ApiImplicitParams注解，并且可以同时设置请求参数与header参数，如下：
@Api(tags = "用户管理")
@RestController
@RequestMapping("user")
public class UserController {@ApiOperation(value = "根据Id查询", notes = "根据Id查询", response = UserParam.class)@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "数据id", paramType = "path", dataType = "int", required = true),@ApiImplicitParam(name = "name", value = "数据名称", paramType = "path", dataType = "String", required = true),@ApiImplicitParam(name = "token", value = "token令牌", paramType = "header", required = true, dataType = "String")})@GetMapping// @RequestParam接收的参数的类型要与与dataType的类型一致public UserParam getUserRole(@RequestParam int id, @RequestParam String name) {System.out.println("id：" + id);System.out.println("name：" + name);return new UserParam();}
}
效果：
2.5.6 全局参数配置
通过在Knife4j的UI界面，设置全局参数，参数分为header与query两种类型，设置全局参数以后，在接口的调试页面，配置的全局参数会自动进行参数的填充，配置后需要重新刷新页面；
自动填充：
3、分组排序
分组排序的目的是，我们可以按照自定义的序号将接口类进行从上到下的顺序排序；
未开启排序前：
在下图中可以看到在未开启分组排序前Controller中的顺序是登录管理->用户管理，而UI页面的顺序是用户管理->登录管理，看起来顺序是乱的，如果接口多了以后顺序就会更加会乱。
开启排序后：
Knife4j为了解决排序提供了增强功能与@ApiSort(num)注解用于自定义排序，其中num越大排序越靠后，用法如下：
yml配置：
在Knife4j-2.0.6版本后将@EnableKnife4j注解的方式修改为了使用yaml配置
knife4j:enable: true
注解使用：
@Api(tags = "登陆管理")
@ApiSort(1)
@RestController
@RequestMapping("/login")
public class LoginController {............
}@Api(tags = "用户管理")
@ApiSort(2)
@RestController
@RequestMapping("user")
public class UserController {............
}
效果：
4、接口排序
接口排序的目的是，我们可以将一些新写的接口按照自定义的序号进行从上到下的顺序排序；
未开启排序前：
在下图中可以看到在未开启接口排序前Controller中的顺序是基础测试->新增数据，而UI页面的顺序是新增数据->基础测试，看起来顺序是乱的，如果接口多了以后顺序就会更加会乱。
开启排序后：
Knife4j为了解决排序提供了增强功能与@ApiOperationSupport(order = num)注解用于自定义排序，其中num越大排序越靠后，用法如下：
yml配置：
在Knife4j-2.0.6版本后将@EnableKnife4j注解的方式修改为了使用yaml配置
knife4j:enable: true
注解使用：
@Api(tags = "用户管理")
@RestController
public class UserController {@ApiOperation(value = "基础测试", notes = "基础测试")// 排序注解@ApiOperationSupport(order = 1)@GetMapping("/test")public void test() {System.out.println("进入了test接口");}@ApiOperation(value = "新增数据", notes = "新增数据")// 排序注解@ApiOperationSupport(order = 2)@PostMapping("/add")public void insert(@RequestBody UserParam param) {System.out.println("新增用户：" + param);}
}
效果：
5、访问页面权限控制
通过开启页面权限控制使得访问Knife4j接口地址时需要进行账户密码验证，通过Knife4j提供的增强功能实现，用法如下：
yml配置：
在Knife4j-2.0.6版本后将@EnableKnife4j注解的方式修改为了使用yaml配置
knife4j:# 开启增强配置enable: truebasic:enable: true# Basic认证用户名username: admin# Basic认证密码password: 123456
效果：
6、生产环境屏蔽
我们在开发阶段时，是可以任意访问Knife4j文档的，当项目上线以后，我们为了保证不被外部系统访问，在不大量修改代码的情况下，可以使用Knife4j提供的生产环境屏蔽功能，用法如下：
yml配置：
在Knife4j-2.0.6版本后将@EnableKnife4j注解的方式修改为了使用yaml配置
knife4j:# 开启增强配置enable: true# 开启生产环境屏蔽production: true
效果：
7、多个Controller分组
实际开发项目中，我们可以存在多个页面模块，每个模块的controller路径不同，那么可以在Knife4jConfig中配置，多个不同的分组，如下：
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {/*** 创建一个Docket实例，指定controller包路径** @return*/@Bean(value = "system")public Docket system() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo())//分组名称.groupName("系统管理").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.project.system.controller")).paths(PathSelectors.any()).build();}@Bean(value = "wage")public Docket wage() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo())//分组名称.groupName("工资管理").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.project.wage.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API").description("接口详细文档").contact(new Contact("开发者名称", null, "开发者邮箱")).version("1.0").build();}
}
效果：
SpringBoot整合knife4j(swagger)实现前后端分离可视化接口调试与接口测试相关推荐
- Springboot+vue 社团管理系统（前后端分离）
Springboot+vue 社团管理系统(前后端分离) zero.项目功能设计图 一.数据库设计(项目准备) 1.建表 2.表目录 二.前端编写(vue) 1.搭建Vue框架 2.放入静态资源(as ...
- 计算机毕业设计-springboot企业考勤管理系统（前后端分离）员工考勤管理系统-公司日常管理系统java代码
计算机毕业设计-springboot企业考勤管理系统(前后端分离)员工考勤管理系统-公司日常管理系统java代码 注意:该项目只展示部分功能,如需了解,联系咨询即可. 作者:IT跃迁谷 1.开发环境 ...
- SpringBoot+LayUI+MybatisPlus+Echarts图表 前后端分离 实现数据统计功能
前言: 小伙伴们,大家好,我是狂奔の蜗牛rz,当然你们可以叫我蜗牛君,我是一个学习Java快一年时间的小菜鸟,同时还有一个伟大的梦想,那就是有朝一日,成为一个优秀的Java架构师. 首先给各位粉丝朋友 ...
- 毕设：基于SpringBoot+Vue 实现云音乐(前后端分离)
文章目录 一.简介 2.项目介绍 二.功能 2.功能介绍 三.核心技术 1.系统架构图 2.技术选型 五.运行 3.截图 前端界面 后台管理界面 总结 1.完整工程 2.其他 一.简介 2.项目介绍 ...
- SpringBoot+Vue分页实现，前后端分离
一.前期准备 1.简介 熟悉SpringBoot,Mybatis,Vue,Element UI等框架的使用:Vue-cli脚手架工具的使用:掌握前后端分离思想,熟悉单体架构等思想. 2.工具下载(No ...
- springBoot 搭建web项目（前后端分离，附项目源代码地址）
2019独角兽企业重金招聘Python工程师标准>>> 概述 该项目包含springBoot-example-ui 和 springBoot-example,分别为前端与后端,前后端 ...
- 接口入参形式_某小公司RESTful、共用接口、前后端分离、接口约定的实践
点击上方"后端技术精选",选择"置顶公众号" 技术文章第一时间送达! 作者:邵磊 juejin.im/post/59eafab36fb9a045076eccc3 ...
- 某小公司RESTful、共用接口、前后端分离、接口约定的实践
点击上方"方志朋",选择"设为星标" 回复"666"获取新整理的面试资料 作者:邵磊 juejin.im/post/59eafab36fb9 ...
- 某小公司 RESTful、共用接口、前后端分离、接口约定的实践
前言 随着互联网高速发展,公司对项目开发周期不断缩短,我们面对各种需求,使用原有对接方式,各端已经很难快速应对各种需求,更难以提高效率.于是,我们不得不重新制定对接规范.开发逻辑以便快速上线项目. 我 ...
最新文章
- 超算学院计算机系吧,上海交通大学计算机科学与工程系(CSE)
- php 去掉img,php怎样去掉img标签
- 157所中国内地高校上榜！最新世界大学学术排名发布
- 为你详细解读HTTP请求头(header)的具体含意
- CA/TA通信的share memory设计思想解读
- 字节流复制文本文件【应用】
- GitLab 服务器的迁移以及注意点
- 一步步部署基于Windows系统的Jenkins持续集成环境
- H.265：网络视频的高清时代
- Linux系统中僵尸进程的查看与删除
- chm文件打开时提示乱码
- c语言编写dxf文件吗,判断dxf文件的版本
- 一场精彩的比赛——2019年ACM新生赛
- 日语N2听力常用词汇
- 迅捷pdf转换器在线转换——六大转换
- HarmonyOS电脑系统,HarmonyOS
- UDP是全双工通信的吗
- Java中print()\println()\printf()的区别及用法
- POJ1837 DP
- html密码框ml表单文本框,表单组件 PasswordInput 密码输入框 - 闪电教程JSRUN