在 springboot3.x 使用 knife4j 以及常見報錯匯總

引言：?

引入依賴：?

配置文件：?

過濾靜態資源：

?增強模式：

便捷地址訪問：

常見問題：?

注解使用實例：?

📄 ?文檔參考地址?：
SpringBoot 3.x 結合 Swagger3 （Knife4j ）踩坑實錄 - 古渡藍按 - 博客園?🔍

🏛? ?官方文檔地址?：
快速開始 | Knife4j📚

💡 ?背景來源?：
想在微服務項目使用 Knife4j，但是找了很多文檔使用后訪問地址無法顯示 😵。經過實踐和排查，終于解決了問題 ?！

引言：?

首先，重點強調 Spring Boot 3.x 只支持 OpenAPI3 規范：

Knife4j提供的starter已經引用springdoc-openapi的jar，開發者需注意避免jar包沖突
JDK版本必須 >= 17
詳細Demo請參考knife4j-spring-boot3-demo

在 Spring Boot 3.x 項目中，如果你看到?swagger-annotations?依賴，通常意味著你正在使用 ?Springfox Swagger?（如?springfox-swagger2），而它 ?不兼容 Spring Boot 3.x?（因為 Spring Boot 3 遷移到了 Jakarta EE 9+，而 Springfox 仍依賴舊的?javax.servlet?包）。?

<!-- 刪除這些 Springfox 依賴 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.10.5</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.10.5</version>
</dependency>

SpringDoc 是 Spring Boot 3.x 的官方推薦替代方案，完全兼容 Jakarta EE 9+：?

Springfox (舊)	SpringDoc (新)	作用
`@Api`	`@Tag`	類級別的 API 描述
`@ApiOperation`	`@Operation`	方法級別的 API 描述
`@ApiParam`	`@Parameter`	參數描述
`@ApiModel`	`@Schema`	模型描述

所以我們需要更換新的依賴，也就是Knife4j4.x，這樣才能在?Spring Boot 3.x 項目中使用。

引入依賴：?

首先引入依賴：

<!--   添加swagger核心依賴-->
<dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-core</artifactId><version>2.2.20</version>
</dependency>
<!--添加knife4j依賴-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version>
</dependency>
<!--添加Springdoc依賴-->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-api</artifactId><version>2.2.0</version>
</dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-configuration-processor</artifactId><optional>true</optional>
</dependency>
<!--僅添加上述依賴，仍有可能報錯，需補充以下依賴-->
<dependency><groupId>com.fasterxml.jackson.module</groupId><artifactId>jackson-module-jakarta-xmlbind-annotations</artifactId><version>2.13.3</version>
</dependency>
<dependency><groupId>javax.xml.bind</groupId><artifactId>jaxb-api</artifactId><version>2.4.0-b180830.0359</version>
</dependency>

配置文件：?

我們一共要引入三個配置類和一個配置文件：

引入配置文件，這里因為我在開發微服務，所以在bootstrap.yml進行配置，如果正常開發Springboot項目的話，在application.yml配置即可：

盡需改寫文檔掃描包路徑即可，配置成自己項目的controller包路徑。?

server:servlet:context-path: /contentport: 63040# springdoc-openapi項目配置
springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: 'default'paths-to-match: '/**'# 生成文檔所需的掃包路徑，一般為啟動類目錄packages-to-scan: com.xuecheng.content.api
# knife4j的增強配置，不需要增強可以不配
knife4j:# 是否啟用增強設置enable: true# 是否啟用登錄認證basic:enable: trueusername: adminpassword: 123456setting:language: zh_cnenable-version: trueenable-swagger-models: trueswagger-model-name: 用戶模塊

過濾靜態資源：

Spring MVC配置類，主要用于處理網站圖標(favicon.ico)的請求

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.http.HttpStatus;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;/*** @Classname FaviconConfiguration* @Description 添加配置文件，處理favicon.ico請求* @Version 1.0.0* @Date 2025/5/26 13:39* @Created by Administrator*/
@SpringBootConfiguration
public class FaviconConfiguration implements WebMvcConfigurer {@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(new HandlerInterceptor() {@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {if (!"GET".equalsIgnoreCase(request.getMethod()) || !request.getRequestURI().toString().equals("/favicon.ico")) {return true;}response.setStatus(HttpStatus.NO_CONTENT.value()); // 設置狀態碼為204 No Contentreturn false;}}).addPathPatterns("/**");}
}

?增強模式：

自定義生成的Swagger/OpenAPI文檔的展示信息，提供一些項目信息或者個人的信息。

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.ExternalDocumentation;
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.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import java.util.ArrayList;
import java.util.List;/*** Swagger2配置信息* 這里分了兩組顯示* 第一組是api，當作用戶端接口* 第二組是admin，當作后臺管理接口* 也可以根據實際情況來減少或者增加組** @author eleven_lxs* @date 2025-05-26 22:17*/
@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI swaggerOpenAPI(){return new OpenAPI().info(new Info().title("標題")// 信息.contact(new Contact().name("作者").email("郵箱").url("地址"))// 簡介.description("我的API文檔")// 版本.version("v1")// 許可證.license(new License().name("Apache 2.0").url("http://springdoc.org"))).externalDocs(new ExternalDocumentation().description("外部文檔").url("https://springshop.wiki.github.org/docs"));}
}

便捷地址訪問：

?而為了方便直接通過點擊地址直接訪問，我們編寫配置類幫助我們直接訪問：

import io.micrometer.common.util.StringUtils;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.ApplicationListener;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;import java.net.InetAddress;
import java.net.UnknownHostException;
import java.util.Arrays;
import java.util.Optional;/*** @Classname DocumentationConfig* @Description TODO* @Version 1.0.0* @Date 2025/5/26 15:28* @Created by Administrator*/
@Configuration
@Slf4j
public class DocumentationConfig implements ApplicationListener<ApplicationReadyEvent> {@Autowiredprivate Environment env;@Overridepublic void onApplicationEvent(ApplicationReadyEvent event) {String protocol = env.getProperty("server.ssl.key-store") != null ? "https" : "http";System.out.println(env);// 獲取端口（添加默認值8080）String serverPort = env.getProperty("server.port", "8000");// 處理contextPath（避免null拼接）String contextPath = Optional.ofNullable(env.getProperty("server.servlet.context-path")).orElse("");String docPath = contextPath + "/doc.html";// 獲取主機地址String hostAddress;try {hostAddress = InetAddress.getLocalHost().getHostAddress();} catch (UnknownHostException e) {hostAddress = "localhost";log.warn("無法獲取主機IP，使用默認地址: localhost");}log.info("""----------------------------------------------------------\t應用程序 "{}" 已啟動\t文檔訪問地址:\t本地: \t{}://localhost:{}{}\t外部: \t{}://{}:{}{}\t激活配置: \t{}----------------------------------------------------------""",env.getProperty("spring.application.name", "默認應用"),protocol, serverPort, docPath,protocol, hostAddress, serverPort, docPath,Arrays.toString(env.getActiveProfiles()));}
}

常見問題：?

如果是開發微服務，這里可能會出現?http://localhost:63040/doc.html?,這里我的問題是出自在bootstrap.yml是Spring Cloud的配置文件，但在普通Spring Boot應用中不會自動加載，如果想使用，要添加spring-cloud-starter-bootstrap依賴才能生效：

<!-- 使bootstrap.yml生效 -->
<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-bootstrap</artifactId><version>4.1.5</version> <!-- 與Spring Boot版本匹配 -->
</dependency>

隨后在啟動類下面可以添加代碼進行測試：

@SpringBootApplication
public class ContentApplication {public static void main(String[] args) {ConfigurableApplicationContext context = SpringApplication.run(ContentApplication.class, args);printEnvInfo(context);}private static void printEnvInfo(ConfigurableApplicationContext context) {Environment env = context.getEnvironment();System.out.println("\n=== 應用配置信息 ===");System.out.println("應用名稱: " + env.getProperty("spring.application.name"));System.out.println("服務端口: " + env.getProperty("server.port"));System.out.println("上下文路徑: " + env.getProperty("server.servlet.context-path"));System.out.println("激活Profile: " + Arrays.toString(env.getActiveProfiles()));System.out.println("數據庫URL: " + env.getProperty("spring.datasource.url"));System.out.println("Swagger路徑: " + env.getProperty("springdoc.swagger-ui.path"));}
}

?而我為了方便，我直接配置了一個新的application.yml，發現一樣好使：

server:port: 63040

另外如果還是沒有顯示，那么去檢查你的 SecurityConfig?配置，確保?SecurityConfig 放行所有文檔路徑：

@Configuration
public class SecurityConfig {@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {http.authorizeHttpRequests(auth -> auth.requestMatchers("/content/swagger-ui/?**?","/content/v3/api-docs/?**?","/content/doc.html","/content/webjars/?**?").permitAll().anyRequest().authenticated());return http.build();}
}

注解使用實例：?

import com.xuecheng.base.model.PageParams;
import com.xuecheng.base.model.PageResult;
import com.xuecheng.content.model.dto.QueryCourseParamsDto;
import com.xuecheng.content.model.po.CourseBase;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;@Tag(name = "課程信息管理接口", description = "課程信息管理接口")  // 替代 @Api
@RestController
public class CourseBaseInfoController {@Operation(summary = "課程查詢接口")  // 替代 @ApiOperation@PostMapping("/course/list")public PageResult<CourseBase> list(@Parameter(description = "分頁參數") PageParams pageParams,  // 替代 @ApiParam@Parameter(description = "查詢條件") @RequestBody(required = false) QueryCourseParamsDto queryCourseParamsDto) {CourseBase courseBase = new CourseBase();courseBase.setName("測試名稱");courseBase.setCreateDate(LocalDateTime.now());List<CourseBase> courseBases = new ArrayList<>();courseBases.add(courseBase);return new PageResult<>(courseBases, 10, 1, 10);}
}

import lombok.Data;
import lombok.ToString;
import io.swagger.v3.oas.annotations.media.Schema;@Data
@ToString
@Schema(name = "PageParams", description = "分頁查詢參數") // 類級別描述（可選）
public class PageParams {@Schema(description = "頁碼", example = "1", defaultValue = "1")private Long pageNo = 1L;@Schema(description = "每頁記錄數", example = "30", defaultValue = "30")private Long pageSize = 30L;public PageParams() {}public PageParams(Long pageNo, Long pageSize) {this.pageNo = pageNo;this.pageSize = pageSize;}
}