文章目录
- 1、简介
- 2、生成文档
- 3、系列注解
- 3.1、@Api
- 3.2、@ApiResponses和@ApiResponse
- 3.3、@ApiOperation
- 3.4、@Pathyvariable⭐
- 3.5、@RequestBody
- 3.6、@ApiOperationSupport
- 3.7、@ApiImplicitParams 和 @ApiImplicitParam
- 3.8、@ApiModel
- 3.9、@ApiModelProperty
🍃作者介绍：双非本科大三网络工程专业在读，阿里云专家博主，专注于Java领域学习，擅长web应用开发、数据结构和算法，初步涉猎Python人工智能开发和前端开发。
🦅主页：@逐梦苍穹
📕项目专栏：您的一键三连，是我创作的最大动力🌹
1、简介
Knife4j 是一款基于 Swagger 的开源 API 文档生成工具，它提供了一套简洁的界面来展示和测试你的 API。Knife4j 使得 API 文档的编写、查看和测试变得更加方便，同时支持在线调试接口。
以下是 Knife4j 的一些主要特性和优势：
- 基于 Swagger： Knife4j 是 Swagger 的一个增强版本，它利用 Swagger 注解来生成 API 文档，能够自动生成接口文档、测试接口等信息。
- 美观的界面： Knife4j 提供了一个直观、美观的界面，使得 API 文档更易于阅读和理解。它支持显示接口的请求和响应参数、响应示例、参数类型等详细信息。
- 在线调试： Knife4j 允许用户在界面中直接进行 API 接口的测试和调试，无需额外的工具。你可以在文档页面直接输入参数，模拟请求，并查看实时的响应。
- 接口分组： 可以将接口按照业务逻辑或其他标准进行分组，使得文档更具有组织性和可读性。
- 代码生成： Knife4j 支持通过在线界面生成前端调用 API 的代码片段，包括 Java、Spring Cloud Feign、JavaScript 等。
- 易于集成： Knife4j 提供了简单的集成方式，支持 Spring Boot 项目，只需要引入相应的依赖即可。
- 自定义配置： 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属性配置是否必须提交此请求参数（并不具备检查功能）
