本文转自测试人社区,原文链接:https://ceshiren.com/t/topic/30445
一, Swagger作用
- 前后端分离开发更加方便,有利于团队协作
- 接口文档在线自动生成,降低后端开发编写接口文档负担
- 功能测试
二, 导入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
三, 解决启动问题,新建SwaggerConfiguration 类
package com.ceshiren.springtest.config;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
import springfox.documentation.spring.web.plugins.WebFluxRequestHandlerProvider;
import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
import java.lang.reflect.Field;
import java.util.List;
import java.util.stream.Collectors;
@Configuration
//@EnableSwagger2 //开启swagger注解支持 有了这个注解,就可以去整体的项目下/controller包下扫描其他的swagger注解
public class SwaggerConfiguration {
@Bean
public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
return new BeanPostProcessor() {
@Override
public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
}
return bean;
}
private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
List<T> copy = mappings.stream()
.filter(mapping -> mapping.getPatternParser() == null)
.collect(Collectors.toList());
mappings.clear();
mappings.addAll(copy);
}
@SuppressWarnings("unchecked")
private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
try {
Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
field.setAccessible(true);
return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
} catch (IllegalArgumentException | IllegalAccessException e) {
throw new IllegalStateException(e);
}
}
};
}
}
四, 配置文件配置
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER
五, 访问:http://localhost:8080/swagger-ui/
六, 自定义配置信息
6.1 在SwaggerConfiguration类添加配置信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 页面标题
.title("spring-test系统")
// 描述
.description("spring-test-lp 接口文档")
// 创建人信息
.contact(new Contact("demi", "", "liupan0721@gmail.com"))
// 项目API版本号
.version("1.0.0")
.build();
}
@Bean
public Docket docket() {
//Swagger 的配置主要围绕Docket bean 进行:
return new Docket(DocumentationType.OAS_30)
//配置是否启用Swagger,如果是false,在浏览器将无法访问,默认是true
.enable(true)
.groupName("spring-test interface")
.apiInfo(apiInfo())
// .globalRequestParameters(globalRequestParameters())
//在定义Docket bean 之后,它的select()方法返回一个ApiSelectorBuilder的实例,它提供了一种控制 Swagger 暴露的端点的方法
.select()
//any - 任何请求都扫描 ; none - 任何请求都不扫描 ; basePackage - 扫描指定对应的包名下的controller
// .apis(RequestHandlerSelectors.any())
.apis(RequestHandlerSelectors.basePackage("com.ceshiren.springtest"))
.paths(PathSelectors.any()).build();
//我们可以在RequestHandlerSelectors和PathSelectors的帮助下配置用于选择RequestHandler的谓词。对两者都使用any()将使我们的整个 API 的文档可以通过 Swagger 获得。
}
//生成全局通用参数
private List<RequestParameter> globalRequestParameters() {
List<RequestParameter> parameters = new ArrayList<>();
// 公共请求参数生成器-token
RequestParameter tokenParameter = new RequestParameterBuilder()
.in(ParameterType.HEADER)//在swagger里显示header
.name("token")//header的参数名为 token
.description("对应的token值")
.required(true)//对应参数是否为必传,如果不是必传参数则设置为false
.query(param -> param.model(model -> model.scalarModel(ScalarType.STRING)))
.build();
//为消费者提供帮助建立模型 更新标量类型
// 公共请求参数生成器-udid
RequestParameter udidParameter = new RequestParameterBuilder()
.in(ParameterType.QUERY)//在swagger里显示header
.name("udid")//header的参数名为 token
.description("设备的ID")
.required(false)//对应参数是否为必传,如果不是必传参数则设置为false
.query(param -> param.model(model -> model.scalarModel(ScalarType.STRING)))
.build();
parameters.add(tokenParameter);
parameters.add(udidParameter);
return parameters;
// Collections.singletonList(parameterBuilder.build());
}
6.2 启动服务验证修改成功
6.3 Swagger四部分布局
- API分组:如果没有配置分组默认是default
- 基本描述:Swagger实例Docket的
apiInfo()
方法中的ApiInfo实例参数配置文档信息 - 请求接口列表:只要被Swagger扫描匹配到的请求都会出现
- 实体列表
6.4 Swagger常用注解
6.4.1 对应类和方法上的注解
@RestController
@Api(tags = "POST请求")
public class PostController {
@ApiOperation("register接口")
@PostMapping(path = "/{module}/register", produces = "application/json")
@ApiImplicitParams({
@ApiImplicitParam(name="module", value="模块名称"),
@ApiImplicitParam(name="desc", value="描述"),
@ApiImplicitParam(name="age", value="年龄")
})
String registerAndParam(@RequestBody UserDto userDto, @PathVariable String module,
@RequestParam String desc, @RequestParam int age){
return "用户登录成功!用户名:" + userDto.getUsername() + ", 密码:" +userDto.getPassword() + ", 模块:"+ module + ", 描述:" +desc + ", 年龄:" +age;
}
}
6.4.2 Swagger 页面展示
6.4.3 实体类及属性上使用的注解实例
@Data
@ApiModel(value = "用户实体类",description = "请求参数的用户实体类")
public class UserDto {
@ApiModelProperty(value = "用户名称", example = "demi", required = true)
String username;
@ApiModelProperty(value = "用户密码", example = "123456", required = true)
String password;
}
6.4.4 Swagger 页面展示
推荐学习
【霍格沃兹测试开发】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 接口自动化测试赛前辅导 / 项目实战
更多软件测试开发视频教程点此
软件测试职业发展
零基础入门
测试必备编程篇
自动化测试
性能测试
测试管理
工程效能篇
面试求职篇
软件测试的面试宝典,内含一线互联网大厂面试真题、面试技巧、软件测试面试简历指导,免费领取!