行业知识
利用Knife4j注解实现Java生成接口文档
文章目录
- 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工程中，生成后端接口文档是非常重要的。
首先是引入依赖：
com.github.xiaoymin knife4j-spring-boot-starter ${knife4j}如果springboot启动的时候显示：
应用程序上下文对象异常-启动bean“documentationPluginsBootstrapper”失败，则导入：
org.hibernate.validator hibernate-validator 6.0.18.Final
或在父工程的pom.xml文件中添加：
spring-boot-starter-parent org.springframework.boot 2.7.3
接下来需要编写一个配置类，初始化接口文档的配置：
package com.xzl.user.config;import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;import lombok.extern.slf4j.Slf4j;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Import;import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * @author 逐梦苍穹 * @date 2024/5/3 14:12 */@Configuration@Slf4j@EnableSwagger2@EnableKnife4j@Import(BeanValidatorPluginsConfiguration.class)// TODO BeanValidatorPluginsConfiguration.classpublic class knife4jConfiguration { /** * 通过knife4j生成接口文档 * @return */ @Bean public Docket docket() { log.info("开始生成接口文档..."); ApiInfo apiInfo = new ApiInfoBuilder() .title("") .version("1.0") .description("") .build(); Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo) .select() .apis(RequestHandlerSelectors.basePackage("com.xzl")) .paths(PathSelectors.any()) .build(); return docket; }}最后，启动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属性配置是否必须提交此请求参数（并不具备检查功能）
