前言
kinfe4j文档地址:https://doc.xiaominfo.com/docs/quick-start
springdoc文档地址:https://springdoc.org/#demos
原本使用的是springfox,自Springboot3开始,knife4j引入了springdoc。
Maven引入
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
Springfox转换Springdoc
参考文档:https://springdoc.org/#migrating-from-springfox
@Api → @Tag 用于类,标识这个类是swagger的资源
@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden 用于类,方法,方法参数,表示这个方法或者类被忽略
@ApiImplicitParam → @Parameter 用于方法,表示单独的请求参数
@ApiImplicitParams → @Parameters 用于方法,包含多个请求参数
@ApiModel → @Schema 用于类 ,表示对类进行说明,用于参数用实体类接收
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY) 参数实体类某个参数不显示到接口文档中
@ApiModelProperty → @Schema 用于方法,字段,表示对model属性的说明或者数据操作更改
@ApiOperation(value = “foo”, notes = “bar”) → @Operation(summary = “foo”, description = “bar”) 用于方法,表示一个http请求的操作
@ApiParam → @Parameter 用于方法,参数,字段说明,表示对参数的添加元数据(说明或是否必填等)
@ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”) 用在@ApiResponses中,一般用于表达一个错误的响应信息
配置文件
一、单模块配置文件
@Configuration
public class SwaggerConfig {
private Info createInfo(String title, String version){
return new Info()
.title(title)
.version(version)
.description("Knife4j集成springdoc-openapi示例")
.termsOfService("http://条款网址")
.license(
new License().name("Apache 2.0")
.url("http://doc.xiaominfo.com"));
}
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(createInfo("测试", "1.0.1"));
}
}
效果:
二、多模块配置文件
@Configuration
public class SwaggerConfig {
@Bean
public GroupedOpenApi allOpenApi(@Value("${springdoc.version}") String appVersion) {
String[] paths = {"/**"};
return GroupedOpenApi.builder().group("总览")
.addOpenApiCustomizer(openApi -> openApi.info(this.createInfo("后台管理系统API", appVersion)))
.pathsToMatch(paths)
.build();
}
@Bean
public GroupedOpenApi sysOpenApi(@Value("${springdoc.version}") String appVersion) {
String[] paths = {"/sys/**"};
return GroupedOpenApi.builder().group("系统管理")
.addOpenApiCustomizer(openApi -> openApi.info(this.createInfo("系统管理API", appVersion)))
.pathsToMatch(paths)
.build();
}
@Bean
public GroupedOpenApi dataOpenApi(@Value("${springdoc.version}") String appVersion) {
String[] paths = {"/data/**"};
return GroupedOpenApi.builder().group("数据管理")
.addOpenApiCustomizer(openApi -> openApi.info(this.createInfo("数据管理API", appVersion)))
.pathsToMatch(paths)
.build();
}
private Info createInfo(String title, String version){
return new Info()
.title(title)
.version(version)
.description("Knife4j集成springdoc-openapi示例")
.termsOfService("http://条款网址")
.license(
new License().name("Apache 2.0")
.url("http://doc.xiaominfo.com"));
}
}
效果:
Auth2.0登录校验
真的是栓Q了,整整配了两天,这东西Knife4j官网上只写了按照OpenAPI3规则进行配置,不说现成的吧,连个案例都莫得,我这个应该是全网第一篇配置Springdoc + knife4j鉴权的文档了。。。。
参考:
Maven引入
springdoc-openapi-starter-webflux-ui必须引入,包括了一些Swagger的东西,且仅支持到2.0.4版本,别问,问就是一个一个试过来的。
<!-- springdoc ui -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
<version>2.0.4</version>
</dependency>
配置文件调整
SwaggerConfig中加入以下代码,就是这个规则卡了整整两天。。。妹想到啊。。。
@Bean
public GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {
return openApi -> {
openApi
.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
.components(openApi.getComponents()
.addSecuritySchemes(HttpHeaders.AUTHORIZATION, new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
.name(HttpHeaders.AUTHORIZATION)
.in(SecurityScheme.In.HEADER)
.flows(new OAuthFlows()
.password(new OAuthFlow()
.tokenUrl("http://localhost:8082/user/info"))))
);
};
}