SpringBoot项目整合Knife4J

最新推荐文章于 2025-10-31 16:00:51 发布
原创 最新推荐文章于 2025-10-31 16:00:51 发布 · 1k 阅读 · 19 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#spring boot #后端 #java

SpringBoot项目整合Knife4J

前言

为什么要使用API文档

首先我们要明白我们为什么要去使用API文档，在前后端脱离开发的情况下，前端程序员无法实时的知道后端接口开发的进度，后端程序员总不能每_开发完一个接口或者更新一次接口_就去wx上去跟前端程序员说，嘿！哥们哥们，我新增了一个接口，这个接口是这样这样子…这样沟通的成本也太高了，而且有时候还说不明白，搞得双方都很难受，在这样的情况下，API文档应运而生。

请添加图片描述

什么是API文档

API 文档是开发者了解 API 功能和如何正确使用的主要来源。它提供了详细的指导，包括请求格式、参数说明、响应结构等，API 文档的重要性在于它作为应用程序编程接口的纲要，为开发者提供了关键的信息，帮助他们正确、高效地使用和集成特定的 API。

Knife4j

官方文档：https://doc.xiaominfo.com/docs/quick-start
开源地址：https://gitee.com/xiaoym/knife4j

在这里插入图片描述

我们来简单介绍一下Knife4j。knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j。

Knife4j的进化史

Knife4j从开源至今,目前主要经历版本的变化，分别如下:

版本

说明

1.0~1.9.6

名称是叫swagger-bootstrap-ui,蓝色风格Ui

1.9.6

蓝色皮肤风格,开始更名，增加更多后端模块

2.0~2.0.5

Ui基于Vue2.0+AntdV重写,黑色风格,参考示例，底层依赖的springfox框架版本是2.9.2,仅提供Swagger2规范的适配

2.0.6~2.0.9

底层springfox框架版本升级至2.10.5,仅提供Swagger2规范的适配

3.0~3.0.3

底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3,过度版本，建议开发者不要使用

4.0~

区分OpenAPI2和Swagger3的Maven坐标artifactId
OpenAPI2规范服务端解析框架稳定在springfox2.10.5
OpenAPI3框架服务端解析跟随springdoc项目更新迭代

Swagger和Knife4J的关系

博主在刚接触Knife4j的时候觉得这和Swagger没什么区别嘛，都是API规范文档的框架，在查阅了部分资料后，知道了他们两个直接的联系。

Knife4j是Swagger-UI的增强版，它是在Swagger-UI的基础上进行了改进和优化，提供了更加完善的交互体验和更加美观的UI设计。同时，它也提供了更多的扩展功能，例如在线调试和多语言支持等。

其实看完Knife4j官方文档的介绍后也差不多知道Knife4j是Swagger的升级版。

名称

开发语言&框架

状态

最后版本

风格

Knife4j

Java、JavaScript、Vue

持续更新

无

黑色

swagger-bootstrap-ui

Java、JavaScript、jQuery

停更

1.9.6

蓝色

SpringBoot整合Knife4j

okk，接下来进行我们的正题，SpringBoot项目如何接入Knife4j。

版本适配

但是在这之前我们要清楚Knife4j与SpringBoot版本之间的关系。

Spring Boot版本

Knife4j Swagger2规范

Knife4j OpenAPI3规范

1.5.x~2.0.0

<Knife4j 2.0.0

>=Knife4j 4.0.0

2.0~2.2

Knife4j 2.0.0 ~ 2.0.6

>=Knife4j 4.0.0

2.2.x~2.4.0

Knife4j 2.0.6 ~ 2.0.9

>=Knife4j 4.0.0

2.4.0~2.7.x

>=Knife4j 4.0.0

>=Knife4j 4.0.0

>= 3.0

>=Knife4j 4.0.0

>=Knife4j 4.0.0

由于目前绝大部分项目使用的还是JDK8，Knife4j OpenAPI3需要JDK版本在17及以上，所以我们就不作介绍。我们这块介绍的是SpringBoot版本在2.4.0~2.7.x，Knife4j版本在 >= 4.0.0，使用Knife4j要注意版本的问题。

实现步骤
1.导入依赖

自4.0版本开始，maven组件的artifactId已经发生了变化。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>{maven仓库最新版本}</version>
</dependency>

在4.0版本之前，maven坐标如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>{<4.0.0版本}</version>
</dependency>
2.编写配置类

给大家看一下我的项目架构，在Knife4jConfig下编写配置类。
在这里插入图片描述

/**
 * Knife4j配置类
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        // 网站标题
                        .title("向阳的Swagger文档")
                        // 描述 可以穿插md语法
                        .description("# 这是描述！")
                        // 服务条款
                        .termsOfServiceUrl("......")
                        // 设置作者 服务器url 邮箱
                        .contact(new Contact("向阳", "http://localhost:9999/demo", "xxx"))
                        // 许可证
                        .license("...")
                        // 许可证url
                        .licenseUrl("....")
                        // 版本
                        .version("1.0")
                        .build())
                .groupName("test测试组")
                .select()
                // 要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.shousi.knife4jdemo.controller"))
                // 要扫描的url
                .paths(PathSelectors.any())
                .build();
    }
}
新建一个controller进行测试

下面是我创建的一个测试接口，类命为TestController。

@Api(tags = "测试模块")
@RestController
@RequestMapping("/test")
public class TestController {
    @GetMapping("/world")
    public String world(){
        return "world knife4j";
    }

    @ApiOperation(value = "打招呼")
    @GetMapping("/hello")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    public String hello(@RequestParam("name") String name){
        return "hello" + name;
    }
}
启动项目

启动项目，访问http://localhost:端口号/doc.html。即可进入API文档。
在这里插入图片描述

Knife4j增强配置

在yml配置文件中添加增强配置，在第一次进入API管理文档时需要填写账号、密码，防止网址泄露让外来人员进行破坏。

knife4j:
  enable: true
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # 用户名
    username: root
    # 密码
    password: 123456

同样可以设置production为false，在生产环境下不开放Knife4j。

knife4j:
  production: false
常用注解

注解

解释

相关参数

@Api

对某个Controller进行详细描述

tags：该controller的名称

@ApiOperation

对某个接口/方法进行详细描述

value：该接口的详细名称/功能

@ApiImplicitParam

对某个接口/方法的单个参数进行详细描述

name：参数的名称
value：参数的描述
required：是否必填
dataType：参数类型

@ApiImplicitParams

对某个接口/方法的多个参数进行详细描述

name：参数的名称
value：参数的描述
required：是否必填
dataType：参数类型

@ApiModel

对某个实体类的基本信息进行描述

description：实体类的描述

@ApiModelProperty

对某个实体类的每个属性的进行详细描述

name：参数的名称
value：参数的描述
required：是否必填
dataType：参数类型

例子展示
实体类注解

当然也可以对实体类进行更详细的配置，例如设置dataType属性类型、required是否必须填写。
在这里插入图片描述

Controller注解

在这里插入图片描述

Knife4j文档导出

相信大家应该都使用过Apifox这款API文档（如果没有使用过可以在评论区留言，下一期可以详细介绍一下），可以将项目的Knife4j文档导入Apifox当中，我们不再用去一步一步手搓文档。

实现步骤
1.进入Apifox选择导入项目

在这里插入图片描述

2.选择Knife4j进行导入

注意！如果你添加了增强配置，需要填写yml配置文件中对应的账户和密码，填写完毕后进行提交。
在这里插入图片描述

导入项目

如果没有项目目录进行新建，如果有的话则选择已有的目录。在这里插入图片描述

选择模块导入

如果是第一次导入的话，建议全部导入，如果需要筛选则自行选择。
在这里插入图片描述

发送请求

发送请求后，我们发现可以正常使用，这样就大功告成啦。
在这里插入图片描述

结语

正确的使用Knife4j可以大大节省时间、开发成本，学会使用Knife4j还是十分重要的！有关于Knife4j的后续以及一些高级用法也会继续更新，希望大家可以多多关注。

请添加图片描述

——??[作者]：
——?[更新]：2024.10.19
——??本人技术有限，如果有不对指正需要更改或者有更好的方法，欢迎到评论区留言。
springboot2与springboot3集成Knife4j
xintgong的博客
10-07 1424
spring2与springboot3快速集成Knife4j
Spring Boot 配置 Knife4j
云胡
09-12 2101
【代码】Spring Boot 配置 Knife4j。
springboot2在swagger2基础上整合knife4j（内附源码，编写于2025.10.31）
最新发布
stylts的博客
10-31 552
（前身是）是一个为基于 Java 的 OpenAPI（Swagger）规范生成 API 文档的增强工具。它本质上是一个 Spring Boot Starter，可以无缝集成到你的 Spring Boot 项目中，将一个功能简陋的 Swagger 原生界面，替换成一个功能强大、界面炫酷的在线 API 文档界面。你可以把它理解为常用注释。
SpringBoot整合knife4j（快速入门超详细版）
热门推荐
weixin_47316183的博客
08-01 4万+
在日常开发中，写接口文档是我们必不可少的，而Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j，适用于单体和微服务项目。怎么样，是不是特别的方便和简单~
springboot2集成knife4j（swagger2）
JustryDeng
03-11 6460
springboot2集成knife4j
springboot配置knife4j
Erica_java的博客
10-26 1141
1.添加依赖 <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency> 2.添加配置
Springboot2整合knife4j过程解析
08-24
Springboot2 整合 knife4j 过程解析 Springboot2 整合 knife4j 过程解析是当前热门的技术栈之一，对于开发人员来说，了解如何将 knife4j 与 Springboot2 进行整合是非常重要的。下面我们将详细介绍 Springboot2 ...
SpringBoot项目整合Knife4j接口文档
诨号无敌鸭的博客
04-19 896
写满接口信息的文档，每条接口包括：请求参数，响应参数，接口地址，接口名称，请求类型，请求格式，备注。
springboot项目整合knife4j【借鉴尚硅谷】
m0_57809109的博客
03-17 565
前后端分离开发模式中，api文档是最好的沟通方式。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。1、及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)2、规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)3、一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)4、可测性 (直接在接口文档上进行测试，以方便理解业务)
Spring Boot 2整合Knife4j自动生成API文档
m0_74205854的博客
04-24 710
springboot3进行使用Knife4j的教程,但是在实际的开发中,还是有很多的项目使用的是springboot2使用Knife4j,所以这期进行介绍springboot2如何的进行整合Knife4j.
【knife4j】springboot2集成knife4j+自动生成接口文档。灰常简单！！！
抓紧学习咯！
08-11 1156
解决依赖注入时的歧义问题，在有多个相同bean时，Spring会优先选择带有@Primary注解的bean进行注入。不同人不同类名，跑不了XXX-common-swagger。打开文档，认真检查接口 数据 返回值 等是否有误。拜拜咯，关注我，下次还能再见。地址，出现如下图表示成功。如有错误，敬请雅正！
SpringBoot整合knife4j
周不老的博客
07-15 2万+
SpringBoot整合knife4j knife4j官方文档地址 之前经常使用swagger2来调试接口，听神仙朋友介绍 knife4j 比较好用。今天试着使用了下。感觉还不错。这里记录下，方便今后学习使用。 目录结构 导入pom依赖 <!--lombok插件--> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactI
SpingBoot2整合Knife4j
qq_63683696的博客
06-01 694
SpingBoot2整合Knife4j
Springboot配置knife4j类(knife4j的使用)
qq_43471945的博客
11-03 619
前后端分离开发模式中，API文档是最好的沟通方式。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。具有以下几个特点：及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)可测性 (直接在接口文档上进行测试，以方便理解业务)
SpringBoot2.x集成knife4j
weixin_51620249的博客
11-30 502
SpringBoot2.x集成knife4j
Java中Spring Boot框架集成Swagger2增强版Knife4j
LeungChunwai的博客
01-29 417
【代码】Spring Boot 框架集成Knife4j。
Springboot使用Knife4j
m0_67401055的博客
08-02 1102
先自我介绍一下，小编13年上师交大毕业，曾经在小公司待过，去过华为OPPO等大厂，18年进入阿里，直到现在。推荐意见使用插件其目的是为了简化内部对接，便利测试和前端调试，以及简化的解决程序员编写文档，在本地环境和测试环境可以使用，考虑到安全问题不要暴露在正式环境。已放在资源上用于做demo测试，有需要的小伙伴可以自行下载，有问题可以及时评论，如没有积分的小伙伴评论提供邮箱地址每天登录看到会后及时发送字，感谢各位。Knife4j分为多个版本每个版本对应的依赖包不同，使用时请阅读官方文档，避免踩坑。...
springboot3.4整合knife4j
06-18
<think>根据用户查询，用户需要SpringBoot3.4整合Knife4j的指南或示例。结合引用内容，Knife4j的4.5.0版本支持SpringBoot3（引用[1]），且SpringBoot3只支持OpenAPI3规范（引用[3]）。以下步骤将指导完成整合：###步骤1:添加Knife4j依赖在`pom.xml`中添加依赖（引用[1]）：```xml<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.5.0</version></dependency>```###步骤2:配置OpenAPI基本信息创建配置类`OpenApiConfig.java`（参考引用[3]）：```javaimportio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Info;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;@ConfigurationpublicclassOpenApiConfig{@BeanpublicOpenAPIcustomOpenAPI(){returnnewOpenAPI().info(newInfo().title("API文档").version("1.0").description("SpringBoot3.4整合Knife4j示例"));}}```###步骤3:配置Knife4j增强模式（可选）在`application.properties`中启用Knife4j增强功能（引用[4]）：```propertiesknife4j.enable=true```###步骤4:配置静态资源访问（若需下载文件）如果涉及文件下载，需配置静态资源路径（引用[5]）：```javaimportorg.springframework.context.annotation.Configuration;importorg.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer;@ConfigurationpublicclassWebConfigimplementsWebMvcConfigurer{@OverridepublicvoidaddResourceHandlers(ResourceHandlerRegistryregistry){registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");//若需访问本地磁盘文件，添加如下配置（示例路径为D:/xm/image/）registry.addResourceHandler("/image/**").addResourceLocations("file:D:/xm/image/");}}```###步骤5:启动并访问文档启动应用后，访问Knife4j文档界面：```http://localhost:8080/doc.html```###注意事项1.**JDK版本**：必须使用JDK17或更高版本（引用[3]）。2.**避免依赖冲突**：Knife4jstarter已包含`springdoc-openapi`，无需重复引入（引用[3]）。3.**SpringSecurity集成**：若项目使用SpringSecurity，需放行Knife4j相关路径（如`/v3/api-docs/**`,`/doc.html`等）。§§相关问题§§1.如何自定义Knife4j文档的界面主题？2.整合Knife4j后如何添加JWT认证支持？3.SpringBoot3.4中如何配置Knife4j的分组功能？</think>### SpringBoot 3.4 整合 Knife4j 完整指南 #### 环境要求 - JDK 17+（SpringBoot 3.x 强制要求）[^3] - SpringBoot 3.4.0 - Knife4j 4.5.0+（支持 OpenAPI 3 规范）[^1][^3] --- ### 整合步骤 #### 1. 添加依赖（关键步骤） 在 `pom.xml` 中添加 Knife4j 的 starter 依赖： ```xml <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId> <version>4.5.0</version> <!-- 匹配SpringBoot 3.4的版本 --> </dependency> ``` > 📌 注意：SpringBoot 3.x 仅支持 OpenAPI 3 规范，必须使用 `knife4j-openapi3-*` 系列依赖[^3] #### 2. 创建 OpenAPI 配置类 新建 `Knife4jConfig.java`： ```java import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import org.springdoc.core.models.GroupedOpenApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class Knife4jConfig { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("SpringBoot 3.4 API") .version("1.0") .description("Knife4j整合示例")); } @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("default") .pathsToMatch("/api/**") // 扫描的接口路径 .build(); } } ``` #### 3. 配置文件增强（可选） 在 `application.yml` 中启用增强模式： ```yaml knife4j: enable: true # 开启Knife4j增强功能[^4] setting: language: zh-CN # 中文界面 enable-footer: false ``` #### 4. 配置静态资源访问（文件下载场景） 若涉及文件下载，需添加资源映射配置[^5]： ```java @Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // Knife4j静态资源 registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); // 本地文件下载路径示例 registry.addResourceHandler("/download/**") .addResourceLocations("file:D:/xm/image/"); } } ``` #### 5. 启动并访问 1. 启动 SpringBoot 应用 2. 访问以下 URL： - 文档页面：`http://localhost:8080/doc.html` - OpenAPI 描述文件：`http://localhost:8080/v3/api-docs` --- ### 常见问题解决 1. **依赖冲突**：确保无其他 Swagger 依赖（如 `springfox`），Knife4j starter 已包含 `springdoc-openapi`[^3] ```xml <!-- 需移除的冲突依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> </dependency> ``` 2. **空文档页面**：检查 Controller 是否在扫描路径内（`@GroupedOpenApi` 配置） 3. **文件下载路径**：本地路径需配置正确的资源映射[^5] > ⚠️ 重点提示：SpringBoot 3.x 不再支持 Swagger 2 注解，需使用 `@Tag`、`@Operation` 等 OpenAPI 3 注解 --- ### 接口注解示例 ```java @RestController @RequestMapping("/api/user") @Tag(name = "用户管理", description = "用户相关操作") // OpenAPI 3 注解 public class UserController { @Operation(summary = "查询用户", description = "根据ID获取用户详情") @GetMapping("/{id}") public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) { // ... } } ```
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值