​🍃作者介绍：双非本科大三网络工程专业在读，阿里云专家博主，专注于Java领域学习，擅长web应用开发、数据结构和算法，初步涉猎Python人工智能开发和前端开发。
🦅主页：@逐梦苍穹
📕项目专栏：您的一键三连，是我创作的最大动力🌹

1、简介

Knife4j 是一款基于 Swagger 的开源 API 文档生成工具，它提供了一套简洁的界面来展示和测试你的 API。Knife4j 使得 API 文档的编写、查看和测试变得更加方便，同时支持在线调试接口。
以下是 Knife4j 的一些主要特性和优势：

1. 基于 Swagger： Knife4j 是 Swagger 的一个增强版本，它利用 Swagger 注解来生成 API 文档，能够自动生成接口文档、测试接口等信息。
2. 美观的界面： Knife4j 提供了一个直观、美观的界面，使得 API 文档更易于阅读和理解。它支持显示接口的请求和响应参数、响应示例、参数类型等详细信息。
3. 在线调试： Knife4j 允许用户在界面中直接进行 API 接口的测试和调试，无需额外的工具。你可以在文档页面直接输入参数，模拟请求，并查看实时的响应。
4. 接口分组： 可以将接口按照业务逻辑或其他标准进行分组，使得文档更具有组织性和可读性。
5. 代码生成： Knife4j 支持通过在线界面生成前端调用 API 的代码片段，包括 Java、Spring Cloud Feign、JavaScript 等。
6. 易于集成： Knife4j 提供了简单的集成方式，支持 Spring Boot 项目，只需要引入相应的依赖即可。
7. 自定义配置： Knife4j 提供了一系列的配置选项，可以根据项目的需求进行自定义配置，以满足不同场景的需求。

总体而言，Knife4j 是一个强大、易用的 API 文档生成工具，适用于 Java 和 Spring Boot 项目，使得 API 的设计、测试和文档生成更加便捷。

2、生成文档

在springboot工程中，生成后端接口文档是非常重要的。
首先是引入依赖：

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>${knife4j}</version>
</dependency>

如果springboot启动的时候显示：
应用程序上下文对象异常-启动bean“documentationPluginsBootstrapper”失败，则导入：

<dependency><groupId>org.hibernate.validator</groupId><artifactId>hibernate-validator</artifactId><version>6.0.18.Final</version>
</dependency>

或在父工程的pom.xml文件中添加：

<parent><artifactId>spring-boot-starter-parent</artifactId><groupId>org.springframework.boot</groupId><version>2.7.3</version>
</parent>

最后，启动springboot工程，访问http://localhost:8080/doc.html即可

3、系列注解

3.1、@Api

@Api用于类，表示标识这个类是swagger的资源
该注解声明在controller类上，最常用的参数是tags：

tags的内容，就是生成的html文档的标题内容：

@Api注解的参数如下：

属性名	数据类型	描述
value	String	字段说明
tags	String[]	标签说明
description	String	详细描述
basePath	String	基本路径可以不配置

3.2、@ApiResponses和@ApiResponse

@ApiResponses：在Rest 接口上使用，用作返回值的描述

@ApiResponse各参数：

属性名称	数据类型	说明
code	String	响应的HTTP状态码
message	String	响应的消息内容
response	Class<?>	用于指定响应体的数据结构，
这个属性可以是实体类的 schema 定义

使用二者：

效果：

3.3、@ApiOperation

@ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义

效果：

3.4、@Pathyvariable⭐

@Pathyvariable是获取get方式，url后面参数，进行参数绑定(单个参数或两个以内参数使用)

3.5、@RequestBody

@RequestBody：在当前对象获取整个http请求的body里面的所有数据(两个以上参数封装成对象使用)

3.6、@ApiOperationSupport

添加在Api中处理请求的方法上，通过此注解的order属性（int），可以指定排序序号，Knife4j会根据这些数字将各业务/请求资源升序排列，例如：@ApiOperationSupport(order = 1)。

如果出现自定义顺序失灵的情况，原因如下：

3.7、@ApiImplicitParams 和 @ApiImplicitParam

这两个注解是对请求参数的说明：

效果：

3.8、@ApiModel

用来对实体类进行说明，例如：**@ApiModel(value = "测试对象的value")**

3.9、@ApiModelProperty

作用在实体类的参数上，如果处理请求时，参数是封装的POJO类型，需要对各请求参数进行说明时，应该在此POJO类型的各属性上使用此注解，通过此注解的value属性配置请求参数的名称，通过requeired属性配置是否必须提交此请求参数（并不具备检查功能）