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

>= Knife4j 4.0.0

>= 3.0

>= Knife4j 4.0.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”));
  }

  }

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