SpringBoot3中配置Knife4j

Knife4j 文档请求异常

做项目时容易碰到的两种 Knife4j 文档请求异常：

依赖版本导致的请求异常
配置Spring MVC的消息转换器导致的请求异常

本文主要讲的是依赖版本导致的请求异常

1. 依赖版本导致的请求异常

关于 SpringBoot 和 Knife4j 的版本兼容性问题：该表来自官方文档：

https://doc.xiaominfo.com/docs/quick-start/start-knife4j-version

Knif4j Swagger2 规范的 Maven 依赖是：

XML 复制代码

<dependency>

        <groupId>com.github.xiaoymin</groupId>

        <artifactId>knife4j-spring-boot-starter</artifactId>

        <version>3.0.3</version>

 </dependency>

Knife4j OpenAPI3 规范的 Maven 依赖是：

XML 复制代码

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

🆗，现在有两个问题

（1）官方文档这里容易让人造成误解，Knif4j Swagger2 规范是没有 >=4.0.0 的版本的，最高版本也就 3.0.3，所以 SpringBoot3 的项目是必须使用 Knife4j OpenAPI3 规范的，否则无论你怎么搞都会显示 Knife4j 文档请求异常

（2）我当前时间是 2026/4/17 ，我的 Maven 是配置了阿里云镜像的，但我发现我在尝试引入Knife4j OpenAPI3 规范的 Maven 依赖时一直爆红，说找不到该依赖，后来才发现原来是这个依赖在阿里云镜像库中没有，气死人了。解决方案是：打开 maven 安装目录下的 conf/settings.xml，把配置阿里云镜像的 <mirror> 先去掉，使用 maven 默认的远程仓库下载该依赖即可

所以，我们需要在 SpringBoot3 导入以下依赖，这是使用 Knife4j 文档的前提

XML 复制代码

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

2. SpringBoot3中使用 Knife4j

（1）导入 Knife4j 依赖

XML 复制代码

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

（2）编写 Knife4j 配置文件 knife4Config，该文件主要进行 Knife4j 的属性配置，如：作者、版本、接口分组等

java 复制代码

package com.atguigu.config;
import io.swagger.v3.oas.models.OpenAPI;
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;

/**
 * Knife4j整合Swagger3 Api接口文档
 */
@Configuration
public class Knife4jConfig {

    @Bean
    public GroupedOpenApi adminApi() { // 创建了一个api接口的分组
        return GroupedOpenApi.builder()
                .group("headline-api") // 分组名称
                .pathsToMatch("/headline/**") // 接口请求路径规则
                .build();
    }
    @Bean
    public GroupedOpenApi userApi() { // 创建了一个api接口的分组
        return GroupedOpenApi.builder()
                .group("user-api") // 分组名称
                .pathsToMatch("/user/**") // 接口请求路径规则
                .build();
    }

    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info() // 基本信息配置
                        .title("微头条Api接口文档") // 标题
                        .description("微头条项目接口服务...") // 描述Api接口文档的基本信息
                        .version("v1.0.0") // 版本
                        // 设置OpenAPI文档的联系信息，包括联系人姓名为"马伟驰"，邮箱为"patrick@gmail.com"。
                        .contact(new Contact().name("马伟驰").email("1810932724.com"))
                        // 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );
    }
}

（3）定义配置类 MvcConfig，设置静态资源映射，将 Knife4j 相关资源放行，保证生成的接口文档能够正常进行展示

java 复制代码

@Configuration
public class MvcConfig implements WebMvcConfigurer {
    
    /**
     * 设置静态资源映射
     * @param registry
     */
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

（4）一些注解的使用

|---------------------------------|------------------------|
| 注解 | 说明 |
| @Scheama(description = "" ) | 标记实体类属性 |
| @Tag(name = "") | 标记Controller层（放在类上） |
| @Operations(summary="") | 标记Controller层方法（放在方法上） |

这里用不用看个人选择，我是感觉直接看接口名更清晰

（5）启动项目，访问项目根路径/doc.html 即可访问 Knife4j 接口文档：

headline-api 和 user-aip 即我们在 knife4Config 中创建的两个接口分组，headline-controller 即控制层，下拉列表是控制层对应的方法

（6）接口测试

随后点击调试，设置好请求参数，点击发送即可完成接口调试