SpringBoot3.x整合Knife4j接口文档

 更新时间:2025年06月29日 11:17:39   作者:木子空间Pro  
SpringBoot整合Knife4j来生成和展示接口文档是一种流行的做法,特别是在需要提供RESTful API文档时,下面就来介绍一下如何实现,具有一定的参考价值,感兴趣的可以了解一下

记录下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"));
    }
}

image-20250628121047365

3.用法细节

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

application.yml配置如下:

knife4j:
  enable: true
  basic:
    enable: true
    username: xxx
    password: xxx

image-20250628120355691

原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

image-20250628121019994

附录:可能会遇到问题

问题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.icostatic/ 目录。(如果你不关心这个 favicon,可以忽略这个异常)

image-20250628110509058

问题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内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家! 

相关文章

  • JDBC 与 MyBatis从基础到实践

    JDBC 与 MyBatis从基础到实践

    JDBC(Java Database Connectivity)即 Java 数据库连接,是 Java 语言中用来规范客户端程序如何来访问数据库的应用程序接口,提供了诸如查询和更新数据库中数据的方法,这篇文章主要介绍了JDBC 与 MyBatis从基础到实践,需要的朋友可以参考下
    2025-04-04
  • 浅析如何利用Spring AI构建一个简单的问答系统

    浅析如何利用Spring AI构建一个简单的问答系统

    Spring AI是Spring生态系统的最新成员,旨在简化AI服务与Spring应用的集成过程,本文小编就来和大家简单介绍一下如何利用Spring AI构建一个简单的问答系统吧
    2025-05-05
  • IDEA中如何引入spring的命名空间

    IDEA中如何引入spring的命名空间

    这篇文章主要介绍了IDEA中如何引入spring的命名空间问题,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2023-04-04
  • Java中实现线程的超时中断方法实例

    Java中实现线程的超时中断方法实例

    之前在使用Java实现熔断降级组件的时候,需要实现接口请求的超时中断,通过查找相关资料了解了相关的方法,下面这篇文章主要给大家介绍了关于Java中实现线程的超时中断的相关资料,需要的朋友可以参考下
    2018-06-06
  • 浅谈Java高并发解决方案以及高负载优化方法

    浅谈Java高并发解决方案以及高负载优化方法

    这篇文章主要介绍了浅谈Java高并发解决方案以及高负载优化方法,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2021-08-08
  • 一文搞懂spring boot本地事务@Transactional参数

    一文搞懂spring boot本地事务@Transactional参数

    这篇文章主要介绍了spring boot本地事务@Transactional参数详解,本文通过示例代码图文相结合给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2021-10-10
  • 最简单的在IntelliJ IDEA导入一个本地项目教程(图文)

    最简单的在IntelliJ IDEA导入一个本地项目教程(图文)

    这篇文章主要介绍了最简单的在IntelliJ IDEA导入一个本地项目教程(图文),文中通过图文介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2020-08-08
  • 详谈Java静态动态的问题

    详谈Java静态动态的问题

    下面小编就为大家带来一篇详谈Java静态动态的问题。小编觉得挺不错的,现在就分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2017-09-09
  • Java使用wait/notify实现线程间通信上篇

    Java使用wait/notify实现线程间通信上篇

    wait()和notify()是直接隶属于Object类,也就是说所有对象都拥有这一对方法,下面这篇文章主要给大家介绍了关于使用wait/notify实现线程间通信的相关资料,需要的朋友可以参考下
    2022-12-12
  • 浅谈Java中浮点型数据保留两位小数的四种方法

    浅谈Java中浮点型数据保留两位小数的四种方法

    今天在进行开发的过程中遇到了一个小问题,是关于如何将double类型的数据保留两位小数。具有一定的参考价值,本文就详细的介绍一下
    2021-09-09

最新评论