Springboot3 + knife4j(springdoc) 框架整合

前言

kinfe4j文档地址：https://doc.xiaominfo.com/docs/quick-start
springdoc文档地址：https://springdoc.org/#demos
原本使用的是springfox，自Springboot3开始，knife4j引入了springdoc。

Maven引入

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starterartifactId>
    <version>4.3.0version>
dependency>
1
2
3
4
5

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"));
  }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

效果：

二、多模块配置文件

@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"));
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

效果：

Auth2.0登录校验

真的是栓Q了，整整配了两天，这东西Knife4j官网上只写了按照OpenAPI3规则进行配置，不说现成的吧，连个案例都莫得，我这个应该是全网第一篇配置Springdoc + knife4j鉴权的文档了。。。。

参考：

• 在 webflux 环境中使用 Spring Security
• Spring官方：OAuth 2.0 Resource Server JWT
• https://editor.swagger.io/

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>
1
2
3
4
5
6

配置文件调整

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"))))
                   );
    };
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

效果