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

桃吱咬咬_

已于 2024-12-24 18:39:22 修改

阅读量7.6k

点赞数 61

分类专栏：合集 - Java学习笔记文章标签： java spring boot

于 2024-07-08 09:16:43 首次发布

本文链接：https://blog.csdn.net/zzm_0525/article/details/140256118

版权

合集 - Java学习笔记专栏收录该内容

5 篇文章

订阅专栏

文章目录

前言
一、Spring Boot 3.0整合Knife4j
二、OpenApi 3注解的使用规范
三、使用步骤
四、重启项目并访问接口文档
五、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）

<!-- Swagger3-knife4j依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

其实现在就可以使用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;

/**
 * <p>
 * 编码格式常量类
 * </p>
 *
 * @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.*;

/**
 * <p>
 * 设置WebMvc相关配置
 * </p>
 *
 * @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.*;

/**
 * <p>
 * Knife4j配置类
 * </p>
 *
 * @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("\n----------------------------------------------------------\n\t" +
                        "Application: '{}' is running Success! \n\t" +
                        "Local URL: \thttp://localhost:{}\n\t" +
                        "Document:\thttp://localhost:{}/doc.html\n" +
                        "----------------------------------------------------------",
                env.getProperty("spring.application.name"),
                env.getProperty("server.port"),
                env.getProperty("server.port"));
    }

}