Springboot 3项目整合Knife4j接口文档（接口分组详细教程）

文章目录

前言
一、Spring Boot 3.0整合Knife4j
二、OpenApi 3注解的使用规范
三、使用步骤
- 1.Spring Boot 3.0项目中使用knife4j
- 2.在application.yml中添加knife4j相关配置
- 3.设置WebMvc相关配置（解决封装统一异常处理后doc.html无法打开的问题）
- 4.创建Knife4j的配置文件
- 5.添加实体类信息
- 6.在controller下新建security和system文件夹，添加相应接口进行测试
四、重启项目并访问接口文档
五、Springboot启动类优化

前言

springboot 3开始javax包改成了jakarta，而swagger-oas等包中依然使用的是javax，所以报错。另外springfox已经停止更新有段时间了，并且不支持OpenAPI 3标准，升级Springboot 3.0以后会有更多问题暴露出来。而SpringBoot 3只支持OpenAPI 3规范，因此Spring官网推荐了Springdoc

OpenApi 3的规范，目前针对Java的Spring Boot项目，主要支持的有2个版本：

springfox 3.0.0：同时兼容OpenAPI 2以及OpenAPI 3，但是停更很久了
springdoc-openapi：兼容OpenAPI 3规范，更新速度频繁
Knife4j：在只有的OpenAPI 3规范中，底层基础框架选择springdoc-openapi项目，针对Springfox 3.0.0版本会放弃

一、Spring Boot 3.0整合Knife4j

以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐：

Spring Boot版本

Knife4j Swagger 2规范

Knife4j OpenAPI 3规范

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

>= 3.0

>= Knife4j 4.0.0

参考文档：关于Knife4j适配不同Spring Boot版本的说明文档

项目配置：

JDK：23

SpringBoot：3.3.1

Knife4j：4.5.0

温馨提示：

在这里插入图片描述

二、OpenApi 3注解的使用规范

Swagger 3(OpenApi 3) 注解与Swagger 2注解的对比

Swagger 2

OpenAPI 3

注解位置

作用

@Api

@Tag(name = “接口类名”,description = “接口类描述”)

Controller类

描述此controller的信息

@ApiOperation(value = “接口方法描述”)

@Operation(summary =“接口方法描述”)

Api端口方法

描述此Api的信息

@ApiImplicitParams

@Parameters

Api端口方法

描述参数信息

@ApiImplicitParam

@Parameter(description=“参数描述”)

Api方法的参数

描述参数信息

@ApiParam

@Parameter(description=“参数描述”)

Api方法的参数

@ApiIgnore

@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden

用在各种地方，用于隐藏其Api

@ApiModel

@Schema

DTO类

用于Entity，以及Entity的属性上

@ApiModelProperty

@Schema

DTO属性

用于Entity，以及Entity的属性上

参考链接: 从 Springfox Swagger 2 迁移到 Springdoc Open API

三、使用步骤

1.Spring Boot 3.0项目中使用knife4j

在pom.xml文件中导入knife4j的依赖（本文springboot的版本是3.3.1）
com.github.xiaoymin knife4j-openapi3-jakarta-spring-boot-starter 4.5.0

其实现在就可以使用Knife4j了，暂不做其他配置，启动项目，浏览器输入http://localhost:8080/doc.html查看接口文档

由于我们没有进行任何的属性配置，所以看到的页面是knife4j的初始页面

在这里插入图片描述

2.在application.yml中添加knife4j相关配置

# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true    # 开启knife4j,无需添加@EnableKnife4j注解
  setting:
    language: zh_cn   #中文
    swagger-model-name: 实体列表   #默认为: Swagger Models
  basic: # 开启Swagger的Basic认证功能,默认是false
    enable: true
    username: admin
    password: 123456

3.设置WebMvc相关配置（解决封装统一异常处理后doc.html无法打开的问题）

定义一个编码格式常量类，里面存储静态资源地址（封装起来便于使用和维护）

package com.patrick.blog.constant;

/**
- 编码格式常量类
- @author Patrick
- @since 2025-1-1
  */
  public class SystemConstant {
  
  /**
  - Knife4j接口文档接口分组和分组路径
    */
    public static class Knife4j {
    
    /**
    - 接口分组
      */
      public static final String SECURITY = “权限管理”;
      public static final String SYSTEM = “系统管理”;
    /**
    - 接口分组路径
      */
      public static final String SECURITY_PATH = “com.patrick.blog.controller.security”;
      public static final String SYSTEM_PATH = “com.patrick.blog.controller.system”;
      }
  /**
  - 编码常量
    */
    public static class Charset {
    
    /**
    - 编码格式设置
      */
      public static final String JSON_TYPE_UTF8_CHARSET = “application/json;charset=UTF-8”;
  }
```
 /**
  * 允许匿名访问的静态资源路径列表
  */
 public static final String[] STATIC_WITHE_PATH_LIST = new String[]{
         "/",
         "/js/**",
         "/css/**",
         "/img/**",
         "/fonts/**",
         "/index.html",
         "/favicon.ico",
         "/doc.html",
         "/swagger-ui.html",
         "/webjars/**",
         "/swagger-resources/**",
         "/v3/**"
 };

 /**
  * 允许匿名访问的静态资源存放位置列表
  */
 public static final String[] STATIC_WITHE_LOCATION_LIST = new String[]{
         "classpath:/static/",
         "classpath:/public/",
         "classpath:/META-INF/resources/"
 };
```
  }
}
定义系统配置类WebMvcConfig，由于knife4j接口文档属于静态资源，需将相关资源放行

package com.patrick.blog.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import static com.patrick.blog.constant.SystemConstant.Permission.*;

/**
- 设置WebMvc相关配置
- @author Patrick
- @since 2025-1-1
  */
  @Configuration
  public class WebMvcConfig implements WebMvcConfigurer {
  
  /**
  - 解决resources下的静态资源无法访问
  - @param registry 资源映射注册器
    */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    
    // 静态资源映射
    registry.addResourceHandler(STATIC_WITHE_PATH_LIST)
    .addResourceLocations(STATIC_WITHE_LOCATION_LIST)
    .setCachePeriod(0);
    }
}

4.创建Knife4j的配置文件

该文件主要进行Knife4j的属性配置，如：标题、版本、作者信息、接口分组等

package com.patrick.blog.config;

import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import static com.patrick.blog.constant.SystemConstant.Knife4j.*;

/**
- Knife4j配置类
- @author Patrick
- @since 2025-1-1
  */
  @Configuration
  public class Knife4jConfig {
  
  /**
  - 创建权限分组api
  */
  @Bean
  public GroupedOpenApi securityApi() {
  return createRestApi(SECURITY, SECURITY_PATH);
  }
  
  /**
  - 创建系统分组api
  */
  @Bean
  public GroupedOpenApi systemApi() {
  return createRestApi(SYSTEM, SYSTEM_PATH);
  }
  
  /**
  - 创建api
  - @param groupName 分组名称
  - @param basePackage 包路径
  - @return GroupedOpenApi
    */
    public GroupedOpenApi createRestApi(String groupName, String basePackage) {
    return GroupedOpenApi.builder()
    .group(groupName) // 分组名称
    .packagesToScan(basePackage) // 扫描的包路径
    .pathsToMatch(“/**”) // 匹配所有路径
    .addOpenApiCustomizer(openApi -> openApi.info(apiInfo())) // 设置api信息
    .build();
    }
  /**
  - api简介信息
  - @return ApiInfo
    */
    private Info apiInfo() {
    return new Info()
    .title(“Patrick后台管理系统服务接口”) // 标题
    .description(“Patrick后台管理系统服务接口文档…”) // 描述
    .version(“1.0.0”) // 版本号
    .termsOfService(“http://doc.xiaominfo.com”) // 服务条款
    .contact(new Contact().name(“Patrick”).url(“https://github.com/Patrick-Luo-THR”).email(“patrick.luo@163.com”)) // 联系人信息
    .license(new License().name(“Apache 2.0”).url(“http://www.apache.org/licenses/LICENSE-2.0.html”)); // 许可证信息
    }
}

5.添加实体类信息

@Schema(description = “ ”)： 标记实体类属性

@Data
@TableName("t_user")
@Schema(description = "用户实体")
public class User implements Serializable {

    @Schema(description = "用户id")
    private Integer id;
    
    @Schema(description = "用户昵称")
    private String nickname;
    
    @Schema(description = "用户名")
    private String username;

    @Schema(description = "用户密码")
    private String password;

}

6.在controller下新建security和system文件夹，添加相应接口进行测试

@Tag(name = “ ”)： 标记接口类别
@Operation(summary =“ ”)： 标记接口操作

创建(create) – 使用Post方法;
修改(update) – 使用Post方法;

删除(delete) – 使用Delete方法;

@RestController
@Tag(name = “用户管理”)
@RequestMapping(“/user”)
public class UserController {

@Autowired
UserService userService;

/**
 * 用户列表
 * @return
 */
@Operation(summary = "用户列表")
@GetMapping("/list")
public JsonResult list() {
    List<User> userList = userService.findAll();
    return JsonResult.success().data("userList", userList);
}

}

四、重启项目并访问接口文档

访问http://localhost:8080/doc.html，可以看到我们配置的属性已经在页面中显示出来了

在这里插入图片描述

五、Springboot启动类优化

每次都需要打开浏览器输入地址访问，对开发者很不友好，因此采取以下优化

@Slf4j
@SpringBootApplication
public class BlogApplication {
```
public static void main(String[] args) {
    ConfigurableEnvironment env = SpringApplication.run(BlogApplication.class, args).getEnvironment();

    log.info("
```
```
" +
                    "Application: '{}' is running Success! 
" +
                    "Local URL: 	http://localhost:{}
" +
                    "Document:	http://localhost:{}/doc.html
```
" +
“----------------------------------------------------------”,
env.getProperty(“spring.application.name”),
env.getProperty(“server.port”),
env.getProperty(“server.port”));
}

}
项目启动，控制台打印日志如下：