springboot3版本结合knife4j生成接口文档

1.概述

knife4j官网为：介绍 | Knife4j (xiaominfo.com)https://doc.xiaominfo.com/docs/introduction

初步了解的码友可以初步了解一下官网的如下几个模块：

其中在快速开始模块中，不同的springboot版本都有一个使用的案例demo如下图位置，大家可以点击进去，把对应的代码下载到本地，查看是如何使用和引用knife4j的：

总结下来就是：knife4j是基于swagger优化的、比swagger更好用的接口文档生成器。

2.快速集成springboot

个人bibilailai:

以前可以学习某个不复杂的新知识，我的学习方法是：先去官网了解一些概念性的东西，然后找到快速开始的博客，跟着博客的步骤进行快速集成。

但是这次集成knife4j我按照官网的方式+csdn博客的指引，试过多次，要么报错，要么某些增强功能用不了，多少都会有这样那样的问题。最终把官网的案例demo下载下来，然后在自建测试项目的pom.xml文件中添加和demo中一样的knife4j依赖，这样操作就很丝滑了。也是为以后的学习之路找到了一个新的办法。

2.1 引入依赖

在pom.xml文件中加入如下依赖：

 <dependencyManagement><dependencies><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-dependencies</artifactId><version>4.5.0</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><dependencies><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId></dependency>
</dependencies>

我的整个pom.xml文件为：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.3.8-SNAPSHOT</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.knife4j</groupId><artifactId>MyKnife4jDemo</artifactId><version>0.0.1-SNAPSHOT</version><name>MyKnife4jDemo</name><description>Demo project for Spring Boot</description><properties><java.version>17</java.version></properties><dependencyManagement><dependencies><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-dependencies</artifactId><version>4.5.0</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.24</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build><repositories><repository><id>nexus-maven</id><name>nexus-maven</name><url>https://oss.sonatype.org/content/repositories/snapshots/</url></repository></repositories></project>

2.2 配置文件

2.2.1 添加配置文件

添加配置文件Knife4jConfig.java

@Configuration
@EnableKnife4j
public class Knife4jConfig {@Beanpublic OpenAPI openAPI() {return new OpenAPI().info(new Info().title("knife4j-openapi3入门测试").version("1.0").description("knife4j-openapi3项目的接口文档"));}@Beanpublic GroupedOpenApi userAPI() {return GroupedOpenApi.builder().group("用户信息管理").pathsToMatch("/user/**").build();}@Beanpublic GroupedOpenApi userAPIGroup() {return GroupedOpenApi.builder().group("组管理").pathsToMatch("/group/**").build();}
}

2.2.2 appilication.yml配置

#开启增强功能模式
knife4j:enable: true

2.3 使用注解

2.3.1 注解说明

pom中引入的依赖是关于openApi3规范的，所以针对于该规范，对应的注解使用如下：

swagger2规范	openApi规范
@Api:定义接口分组名称	@Tag(name = “接口类描述述”)
@ApiImplicitParam: 单个参数注释	@Operation(summary =“接口方法描述”)
@ApiImplicitParams:多个参数注释	@Parameters：多个参数注释
@ApiModel:实体类定义	@Parameter：单个参数注释
@ApiModelProperty:实体属性定义	@Parameter(hidden = true) ：排除隐藏api
@ApiOperation:接口定义	@Operation(hidden = true)：排除隐藏api
@ApiParam:参数注释	@Hidden：排除或隐藏api
@ApiResponse:响应码	@Schema：DTO实体DTO实体属性
@ApiResponses:多个响应码	@ApiSort(1)：对controller类进行排序
	@ApiOperationSupport(order = 2,author = "张三")对接口进行排序，并指明接口作者

2.3.2 注解使用

@RequestMapping("/user")
@RestController
@Tag(name = "用户控制类")
@ApiSort(1)
public class UserController {@GetMapping("/userName")@ApiOperationSupport(order = 2,author = "张三")@Operation(summary = "获取用户名称")public String getUserName() {return "张三";}@GetMapping("/userNo")@ApiOperationSupport(order = 1,author = "李四")@Operation(summary = "获取用户编码")public String getUserNo() {return "167545";}
}

2.4 运行项目

运行项目后，在浏览器输入：localhost:端口号/doc.html就可以访问如下页面了：

3.knife4j增强特性

可直接参考官网。后续更新...