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相干配置

1. # knife4j的增强配置，不需要增强可以不配
2. knife4j:
3.   enable: true    # 开启knife4j,无需添加@EnableKnife4j注解
4.   setting:
5.     language: zh_cn   #中文
6.     swagger-model-name: 实体列表   #默认为: Swagger Models
7.   basic: # 开启Swagger的Basic认证功能,默认是false
8.     enable: true
9.     username: admin
10.     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”;
        
      
      
    }
    
    1. /**
    2.   * 允许匿名访问的静态资源路径列表
    3.   */
    4. public static final String[] STATIC_WITHE_PATH_LIST = new String[]{
    5.          "/",
    6.          "/js/**",
    7.          "/css/**",
    8.          "/img/**",
    9.          "/fonts/**",
    10.          "/index.html",
    11.          "/favicon.ico",
    12.          "/doc.html",
    13.          "/swagger-ui.html",
    14.          "/webjars/**",
    15.          "/swagger-resources/**",
    16.          "/v3/**"
    17. };
    19. /**
    20.   * 允许匿名访问的静态资源存放位置列表
    21.   */
    22. public static final String[] STATIC_WITHE_LOCATION_LIST = new String[]{
    23.          "classpath:/static/",
    24.          "classpath:/public/",
    25.          "classpath:/META-INF/resources/"
    26. };

    复制代码
    }
    
    
  }
  
  
• 界说系统配置类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 = “ ”)： 标志实体类属性

1. @Data
2. @TableName("t_user")
3. @Schema(description = "用户实体")
4. public class User implements Serializable {
6.     @Schema(description = "用户id")
7.     private Integer id;
8.    
9.     @Schema(description = "用户昵称")
10.     private String nickname;
11.    
12.     @Schema(description = "用户名")
13.     private String username;
15.     @Schema(description = "用户密码")
16.     private String password;
18. }

复制代码

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

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

• 创建(create) – 利用Post方法;
  
• 修改(update) – 利用Post方法;
  
• 删除(delete) – 利用Delete方法;
  @RestController
  @Tag(name = “用户管理”)
  @RequestMapping(“/user”)
  public class UserController {
  
  1. @Autowired
  2. UserService userService;
  4. /**
  5. * 用户列表
  6. * @return
  7. */
  8. @Operation(summary = "用户列表")
  9. @GetMapping("/list")
  10. public JsonResult list() {
  11.     List<User> userList = userService.findAll();
  12.     return JsonResult.success().data("userList", userList);
  13. }

  复制代码
  }
  

---

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

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

---

五、Springboot启动类优化

• 每次都需要打开浏览器输入地址访问，对开发者很不友爱，因此接纳以下优化
  @Slf4j
  @SpringBootApplication
  public class BlogApplication {
  
  1. public static void main(String[] args) {
  2.     ConfigurableEnvironment env = SpringApplication.run(BlogApplication.class, args).getEnvironment();
  4.     log.info("

  复制代码
    

  ---

  1. " +
  2.                     "Application: '{}' is running Success!
  3. " +
  4.                     "Local URL:         http://localhost:{}
  5. " +
  6.                     "Document:        http://localhost:{}/doc.html

  复制代码
  " +
  “----------------------------------------------------------”,
  env.getProperty(“spring.application.name”),
  env.getProperty(“server.port”),
  env.getProperty(“server.port”));
  }
  }
  
• 项目启动，控制台打印日记如下：
  

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。