当前位置：首页 > news >正文

SpringBoot3.x整合Knife4j接口文档

news 来源：原创 2025/6/29 21:27:35

记录下SpringBoot3.x整合Knife4j接口文档时的步骤以及开发中的常见报错问题。

1.依赖

<!--        接口文档，访问地址：ip:port/doc.html-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version>
</dependency>

2.配置

package com.base.config;import io.swagger.v3.oas.models.ExternalDocumentation;
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.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("接口文档标题").version("1.0.0").description("接口描述").contact(new Contact().name("开发者").email("dev@example.com")).license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html"))).externalDocs(new ExternalDocumentation().description("项目主页").url("https://github.com/xxx/xxx"));}
}

3.用法细节

如果不想全部controller都扫描到，可以用@Hidden注解隐藏不显示
在controller类名上加@Tag(name = "xxx")，具体方法名加@Operation(summary = "xxx")
配置文档需登录后访问

在application.yml配置如下：

knife4j:enable: truebasic:enable: trueusername: xxxpassword: xxx

原UI页面显示

在application.yml配置如下：

springdoc:swagger-ui:
#    访问原UI界面：ip:port/swagger-ui/index.htmlpath: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: 'default'paths-to-match: '/**'packages-to-scan: com.base.controller

附录：可能会遇到问题

问题1

控制台提示favicon.ico未找到

org.springframework.web.servlet.resource.NoResourceFoundException: No static resource favicon.ico.at org.springframework.web.servlet.resource.ResourceHttpRequestHandler.handleRequest(ResourceHttpRequestHandler.java:585)at

解决1

加一个 favicon.ico 到 static/ 目录。（如果你不关心这个 favicon，可以忽略这个异常）

问题2

控制台提示.well-known/appspecific/com.chrome.devtools.json未找到

2025-06-28T10:40:49.872+08:00  WARN 9924 --- [nio-8888-exec-4] .m.m.a.ExceptionHandlerExceptionResolver : Resolved [org.springframework.web.servlet.resource.NoResourceFoundException: No static resource .well-known/appspecific/com.chrome.devtools.json.]
org.springframework.web.servlet.resource.NoResourceFoundException: No static resource .well-known/appspecific/com.chrome.devtools.json.at org.sprin

解决2

拦截 .well-known/ 路径，返回空响应或 404（推荐给控制台干净控）

@RestController
public class WellKnownController {@RequestMapping("/.well-known/**")public ResponseEntity<Void> handleUnknownWellKnown() {return ResponseEntity.notFound().build(); // 返回 404，或改为返回 204 无内容}
}