SpringBoot3.x整合Knife4j接口文档
记录下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 {
@Bean
public 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: true
basic:
enable: true
username: xxx
password: xxx

原UI页面显示
在application.yml配置如下:
springdoc:
swagger-ui:
# 访问原UI界面:ip:port/swagger-ui/index.html
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-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 无内容
}
}
到此这篇关于SpringBoot3.x整合Knife4j接口文档的文章就介绍到这了,更多相关SpringBoot3.x整合Knife4j内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!
相关文章
eclipse 如何创建 user library 方法详解
这篇文章主要介绍了eclipse 如何创建 user library 方法详解的相关资料,需要的朋友可以参考下2017-04-04
Spring的拦截器HandlerInterceptor详解
这篇文章主要介绍了Spring的拦截器HandlerInterceptor详解,拦截器是相对于Spring中来说的,它和过滤器不一样,过滤器的范围更广一些是相对于Tomcat容器来说的,拦截器可以对用户进行拦截过滤处理,需要的朋友可以参考下2024-01-01
SpringCloud Config统一配置中心问题分析解决与客户端动态刷新实现
springcloud config是一个解决分布式系统的配置管理方案。它包含了 client和server两个部分,server端提供配置文件的存储、以接口的形式将配置文件的内容提供出去,client端通过接口获取数据、并依据此数据初始化自己的应用2022-10-10


最新评论