springboot整合swagger3,方便开发者直接进行功能测试
依赖
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-boot-starterartifactId>
<version>3.0.0version>
dependency>
.yml文件配置
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
swagger的配置类
/**
* swagger配置类
*/
@Configuration
@EnableOpenApi
@RequiredArgsConstructor
public class SwaggerConfig {
/**
* 用于读取配置文件 application.properties 中 swagger 属性是否开启
*/
@Value("${swagger.enabled}")
Boolean swaggerEnabled;
private final JwtProperties properties;
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
/* 设置安全模式,swagger可以设置访问token */
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.apiInfo(apiInfo())
// 是否开启swagger
.enable(swaggerEnabled)
.select()
// 过滤条件,扫描指定路径下的文件
.apis(RequestHandlerSelectors.basePackage("com.xl.controller"))
.paths(PathSelectors.regex("^(?!/error).*"))
// 指定路径处理,PathSelectors.any()代表不过滤任何路径
//.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
/*作者信息*/
Contact contact = new Contact("xl", "", "[email protected]");
return new ApiInfo(
"Spring Boot 集成 Swagger3 测试",
"Spring Boot 集成 Swagger3 测试接口文档",
"v1.0",
"",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
/**
* 当全局header参数中包含命名为Accpet、Content-Type、Authorization的参数时,参数的定义将被忽略,需要手动添加
* 手动添加Accpet、Content-Type、Authorization到配置中去
*
* 安全模式,这里指定token通过Authorization头请求头传递
* 这里也是配置全局参数Authorization到RequestHeader中
* @return
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> securitySchemes = new ArrayList<>();
securitySchemes.add(new ApiKey("Authorization", "Authorization", "header"));
return securitySchemes;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
return securityContexts;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
}
页面使用
以上就是springboot整合swagger的全部过程,这里我对整合过程中遇到的问题进行说明
swagger在request请求头设置全局变量时,如果直接通过创建一个全局变量的方法,然后在通过globalRequestParameters进行挂载,如果请求头的参数是Accpet、Content-Type、Authorization会被swagger忽略掉。
下面是一般的全局变量配置方法
//生成全局通用参数
private List getGlobalRequestParameters() {
List parameters = new ArrayList<>();
parameters.add(new RequestParameterBuilder()
.name("Authorization")
.description("token")
.required(true)
.in(ParameterType.HEADER)
.query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
.required(false)
.build());
return parameters;
}
上面的方法如果在配置请求头参数时如果用到Accpet、Content-Type、Authorization字段不建议使用,建议使用我最上面提供的案例模板
swagger 忽略某些参数,不出现在文档中
@ApiImplicitParams和@ApiImplicitParam将类中需要展示的元素进行标注,然后使用@ApiIgnore标注在参数上
@ApiOperation(value = "新增角色", httpMethod = "POST")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "角色名称",dataType = "String"),
@ApiImplicitParam(name = "roleKey",value = "角色权限字符串",dataType = "String"),
@ApiImplicitParam(name = "status",value = "角色状态",dataType = "String")
})
@PostMapping
public ResponseEntity<Object> create(@ApiIgnore @RequestBody SysRole sysRole) {
Optional.ofNullable(sysRole.getId())
.orElseThrow(() -> new BadRequestException("不能创建一个已经存在id的角色"));
return ResponseEntity.ok(sysRoleService.insertRole(sysRole));
}