SpringBoot快速教程三整合Knife4j通过SpringBoot3.3.4版本整合目前主流的接口文档框架Knif

Hello，大家好，我是Feri，一枚十多年的程序员，同时也是一名在读研究生，关注我，且看一个平凡的程序员如何在自我成长，CodingSir是我想打造一个编程社区，只为各位小伙伴提供编程相关干货知识，希望在自我蜕变的路上，我们一起努力，努力什么时候开始都不晚，我，从现在开始做起！

一、前言

最近写了几篇关于最新版SpringBoot使用的教程，我看有小伙伴私信就是想要了解一下SpringBoot新版本怎么整合接口文档框架，因为之前都是使用Swagger，但是这个有点旧，那么本篇安排上。

通过SpringBoot3.3.4版本整合目前主流的接口文档框架Knife4j的新版本，因为SpringBoot3只支持OpenAI3规范，所以本篇是通过整合Knife4j的4.4版本进行演示接口文档框架的应用。

注意：jdk至少>=17哈，别问为什么，问了就告诉你！

二、实现

2.1 Swagger

Swagger（丝袜哥）呢，是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

Swagger官网地址：swagger.io/

2.2 Knife4j

Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案，帮助开发者快速聚合使用OpenAPI规范。更名为Knife4j之前,原来的名称是叫swagger-bootstrap-ui，而swagger-bootstrap-ui是原来对swagger-ui的优化，比之更加好看一些。

Knife4j官网地址：doc.xiaominfo.com/

Knife4j v4.0架构图：

Knife4j的版本历史：

Knife4j如果被整合到SpringBoot中，那么就需要看对应的兼容版本，如下所示：

注意，注意：

Knife4j在之前的版本更新中，逐渐提供了一些服务端适配的增强特性功能。

但是开发者应该明白，不管是Swagger2规范还是OpenAPI3规范，Knife4j的最新版本的纯Ui版本，是可以适配Spring Boot所有版本的。

如果你不考虑使用Knife4j提供的服务端增强功能，引入Knife4j的纯Ui版本没有任何限制。只需要考虑不同的规范即可。

2.3 为什么使用Knife4j而不是Swagger

在Spring Boot框架中,Knife4j对于服务端将Spring的开放接口解析成Swagger2或者OpenAPI3规范的框架，也是依赖的第三方框架组件。说明如下：

1.Swagger2规范：依赖Springfox项目，该项目目前几乎处于停更状态，但很多老项目依然使用的是该规范，所以Knife4j在更新前端Ui的同时也继续保持了兼容

2.OpenAPI3规范：依赖Springdoc项目，更新发版频率非常快，建议开发者尽快迁移过来使用OpenAPI3规范,Knife4j后面的重心也会在这里。

所以明白了没？那么现在记下来，SpringBoot的版本尽量建议使用Knife4j哈

2.4 Knife4j核心

首先我们需要明白Knife4j的核心功能，其实就是3部分：

第一，接口文档：通过简单的注解即可实现接口对应的在线文档，这样一旦需求发生改变，去更改代码的时候，接口文档会跟着代码的变化跟着改变，不需要单独维护对应的接口文档，并且内置了一些增强注解，很方便的为接口添加各种说明和标记，让接口调用方，清晰明了即可明白接口该怎么调用，在开发阶段特别好用，特别对于需求渐进明细的项目，真的是按期交付的不二法宝。

第二，接口在线测试：Knife底层是Swagger，所以可以跟方便的在线对接口做测试，简单好用，对于后端研发人员写完接口之后，自测好用不解释😁。

第三，生成离线文档：整个开发阶段结束之后，接口完整没啥问题了，就可以导出对应的离线接口文档，直接收录到项目开发文档，真好使！

注意：

Knife4j这类只能用于开发阶段，一旦项目进入内测或上线，请务必屏蔽掉，要不然，你懂得！

2.5 SpringBoot3整合Knife4j

SpringBoot整合Knife4j的详细步骤：

0.所需环境：jdk>=17，使用SpringBoot3.3.4版本，整合Knife4j4.4版本

1.创建SpringBoot3.3.4的项目

2.编码，实现对应的测试接口代码

核心如下所示：

@RestController
@RequestMapping("/api/food")
public class FoodController {
    /**
     * 新增*/
    @PostMapping("add")
    public R<String> add(@RequestBody Food food){
        return R.ok(food.getName());
    }
    /**
     * 查询*/
    @GetMapping("all")
    public R<List<Food>> all(){
        List<Food>list=new ArrayList<>();
        for (int i = 1; i < 6; i++) {
            list.add(new Food("胡辣汤-"+i,"胡辣，美味",i*3.0));
        }
        return R.ok(list);
    }
}

模拟代码，简单勿怪

3.依赖Knife4j的jar

在pom文件中，添加Knife4j的jar依赖

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
   <version>4.4.0</version>
</dependency>

4.在刚刚写的controller包使用注解

@RestController
@RequestMapping("/api/food")
@Tag(name = "最爱的食物") //修饰类，设置类的说明信息
public class FoodController {
    /**
     * 新增*/
    @Operation(summary = "新增食物") //修饰方法，为方法添加说明信息
    @PostMapping("add")
    public R<String> add(@RequestBody Food food){
        return R.ok(food.getName());
    }
    /**
     * 查询*/
    @Operation(summary = "查询食物")
    @GetMapping("all")
    public R<List<Food>> all(){
        List<Food>list=new ArrayList<>();
        for (int i = 1; i < 6; i++) {
            list.add(new Food("胡辣汤-"+i,"胡辣，美味",i*3.0));
        }
        return R.ok(list);
    }
}

5.对参数类加上注解说明

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Food {
    @Schema(description = "食物名称") //knife4j 为参数属性添加说明
    private String name;
    @Schema(description = "食物说明信息")
    private String info;
    @Schema(description = "食物价格")
    private Double price;
}

6.运行测试

浏览器访问：localhost:8080/doc.html

文档：可以查看具体接口信息，请求方式、请求路径、请求示例、参数说明、返回结果等

调试：在线测试接口

新增：

查询：

好嘞，有没有感受到Knife4j的魅力所在，反正我是感受到了！

2.6 Knife4j常用注解

来来来，又来到了整理的环节，结合刚刚的代码，下面就是我给大家整理好的Knife4j的核心注解，记住要背一下哈：

序号	注解名称	用法	作用
1	@Tag	修饰类	标记类说明信息，name属性
2	@Operation	修饰方法	设置方法的说明信息，summary属性
3	@Schema	修饰属性	设置参数属性的说明信息，description属性
4	@Parameters	修饰方法	内部使用@Parameter，为接口参数设置说明信息
5	@Parameter	修饰方法	接口参数设置说明信息

关于Knife4j的使用，其实只需要记住这3个注解，应对日常的开发就没啥问题啦

其实，Knife4j也有一些配置，可供我们日常开发选择，下面是官网提供的配置信息：

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    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.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

三、总结

好啦，本篇教程就到这里，那你要是认为Knife4j仅仅只有这些那就错了，比如Knife4j还有专门适配Gateway网关，但是我们如果掌握今天所说的这些，对于牛马的我们，完全没问题啦。其实本次想给大家说的，是SpringBoot3.x版本下，怎么整合Knife4j的新版本，你会发现在SpringBoot3.x之后，整合Knife4j的版本有严格要求，否则一访问就会报Knife4j接口文档错误等等的异常。如果你还有什么想继续学习的，欢迎随时联系我，持续给大家带来干货，助力我们快乐工作，幸福生活！

好啦，今天这篇就打这啦，有任何问题可以随时进行评论交流，如果你有什么想要Feri更新的，请关注CodingSir查看更新的内容，也可以随时关注，私信我哟，成长的路上，有你们相伴，真是人生一大幸事！