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 {


    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("knife4j-openapi3入门测试")
                        .version("1.0")
                        .description("knife4j-openapi3项目的接口文档"));
    }

    @Bean
    public GroupedOpenApi userAPI() {
        return GroupedOpenApi.builder().group("用户信息管理").
                pathsToMatch("/user/**").
                build();
    }

@Bean
    public 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";
    }
}