SpringBoot3+支持Knife4j 4.0以上

一、引用Knife4j的starter,Maven坐标

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

二、配置yml

目前给出的是扫描一个大包，后面会有分组的代码

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'all'
      paths-to-match: '/**'
      packages-to-scan: com.quick.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

参考官方中文文档：快速开始 | Knife4j

 三、定义配置文件config

定义一个配置类WebMvcConfiguration，实现静态资源映射，保证生成的接口文档能够正常进行展示

/**
 * 配置类，注册web层相关组件
 */
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始设置静态资源映射...");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

  
}

两种分组方法：

 1、建一个配置类SwaggerConfig，实现接口文档能够分组展示

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("管理端接口")
                .pathsToMatch("/admin/**") // 根据你的实际路径进行配置
                .build();
    }

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("C端接口")
                .pathsToMatch("/user/**") // 根据你的实际路径进行配置
                .build();
    }
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("接口文档")
                        //描叙
                        .description("接口文档")
                        //版本
                        .version("v1")
                        //作者信息，自行设置
                        .contact(new Contact().name("bluefoxyu"))
                        //设置接口文档的许可证信息
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }

}

效果图如下

 

 

 2、在上面的yml的配置类里面也设置了，我设置了扫描的包是user和admin的父包controller，里面的接口是所有子包接口的集合，效果图如下

  group-configs:
    - group: 'all'
      paths-to-match: '/**'
      packages-to-scan: com.quick.controller

 

 

当然也可以直接在yml配置文件里面配置分组信息，那样就不用在配置类里面定义以下代码，具体参考中文官方文档 ：3.1 增强模式 | Knife4j

@Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("管理端接口")
                .pathsToMatch("/admin/**") // 根据你的实际路径进行配置
                .build();
    }

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("C端接口")
                .pathsToMatch("/user/**") // 根据你的实际路径进行配置
                .build();
    }

以下给出修改的yml和完整的yml

    - group: 'admin'
      paths-to-match: '/**'
      packages-to-scan: com.quick.controller.admin
    - group: 'user'
      paths-to-match: '/**'
      packages-to-scan: com.quick.controller.user

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'admin'
      paths-to-match: '/**'
      packages-to-scan: com.quick.controller.admin
    - group: 'user'
      paths-to-match: '/**'
      packages-to-scan: com.quick.controller.user
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

 效果图如下：

 

 

综上所述：两种分组方法任选一种。

上面配置类里面的以下代码则是介绍，也可以在yml里面配置，以下就不再多说。

具体可以参考3.1 增强模式 | Knife4j

@Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("餐途快取项目接口文档")
                        //描叙
                        .description("餐途快取项目接口文档")
                        //版本
                        .version("v1")
                        //作者信息，自行设置
                        .contact(new Contact().name("bluefoxyu"))
                        //设置接口文档的许可证信息
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }

4、实现接口文档的生成

网址：http://localhost:8080/doc.html

5、Swagger3 注解使用（Open API 3）

可参考官方文档里面入门快速案例：快速开始 | Knife4j

@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {

   @Operation(summary = "普通body请求")
   @PostMapping("/body")
   public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok(fileResp);
   }

   @Operation(summary = "普通body请求+Param+Header+Path")
   @Parameters({
           @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
           @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
           @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
   })
   @PostMapping("/bodyParamHeaderPath/{id}")
   public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
       fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
       return ResponseEntity.ok(fileResp);
   }
}

 swagger2和swagger3注解有些变化，具体可以参考：Swagger 2.X Annotations · swagger-api/swagger-core Wiki · GitHub

注意：swagger 3 注解的包路径为io.swagger.v3.oas.annotations.

这里参考了这位博主的博文：Swagger3 注解使用（Open API 3）_swagger3注解-CSDN博客

 下面是我的一些代码改动

//controller

//@Api(tags = "通用接口")
@Tag(name = "通用接口")

//@ApiOperation("文件上传")
    @Operation(summary = "文件上传")



//实体类

@Data
//@ApiModel(description = "员工登录时传递的数据模型")
@Schema(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {

    //@ApiModelProperty("用户名")
    @Schema(description = "用户名")
    private String username;

    //@ApiModelProperty("密码")
    @Schema(description = "密码")
    private String password;

}

 

6、关于Knife4j文档请求异常问题

有可能是springboot版本和Knife4j的版本不一致问题，参考：Knife4j版本参考 | Knife4j

也可参考Knife4j文档请求异常 | Knife4j

Spring Boot版本	Knife4j Swagger2规范	Knife4j OpenAPI3规范
1.5.x~2.0.0	<Knife4j 2.0.0	>=Knife4j 4.0.0
2.0~2.2	Knife4j 2.0.0 ~ 2.0.6	>=Knife4j 4.0.0
2.2.x~2.4.0	Knife4j 2.0.6 ~ 2.0.9	>=Knife4j 4.0.0
2.4.0~2.7.x	>=Knife4j 4.0.0	>=Knife4j 4.0.0
>= 3.0	>=Knife4j 4.0.0	>=Knife4j 4.0.0

还有一种情况我遇到过，这个博主的文章完美解决Knife4j文档请求异常(基于SpringBoot3，查找原因并解决)_standard commons logging discovery in action with -CSDN博客