怎么查看自己网站有没有被百度收录,铁道部网上订票网站素材,达人室内设计网论坛,车载嵌入式软件开发欢迎来到我的博客#xff0c;代码的世界里#xff0c;每一行都是一个故事 精雕细琢的文档体验#xff1a;Spring Boot 与 Knife4j 完美交汇 前言Knife4j 与 Swagger 的区别1. 特性与优劣势对比#xff1a;Knife4j#xff1a;Swagger#xff1a; 2. 选择 Knife4j 的理由代码的世界里每一行都是一个故事 精雕细琢的文档体验Spring Boot 与 Knife4j 完美交汇 前言Knife4j 与 Swagger 的区别1. 特性与优劣势对比Knife4jSwagger 2. 选择 Knife4j 的理由 Knife4j中的注解说明1. 控制器类相关注解Api 注解 2. 接口方法相关注解ApiOperation 注解ApiParam 注解 3. 模型类相关注解ApiModel 注解ApiModelProperty 注解 实战演示引入maven依赖配置类请求vo实现响应VO实现controller实现效果展示图 彩蛋(报错 解决)结语 前言
在代码的世界里有时候注释不足以表达你的思想而一份优雅的 API 文档则能够让你的代码更加生动、易读。今天我们将探讨如何通过整合 Knife4j为你的 Spring Boot 项目添加一把锐利的文档利器。就像在一场精彩的武术表演中每一刀都能展现出独特的艺术魅力Knife4j 也将为你的文档世界带来新的精彩。
Knife4j 与 Swagger 的区别
Knife4j 和 Swagger 是两个用于 API 文档生成和展示的工具它们都基于 OpenAPI以前称为 Swagger规范。下面是 Knife4j 与 Swagger 的区别以及对比它们的特性和优劣
1. 特性与优劣势对比
Knife4j
特性 UI 界面美观 Knife4j 提供了一套漂亮的、易用的 UI 界面展示了 API 文档的信息并支持在线调试和测试。 支持多种注解 Knife4j 支持众多的 Swagger 注解并且提供了一些额外的扩展注解如 ApiImplicitParams、ApiOperationSupport 等。 在线调试 提供了在线调试和测试 API 的功能开发者可以直接在文档中进行接口的测试。 强大的扩展性 支持自定义扩展开发者可以根据需求进行定制化。
优势
UI 界面美观易用性好。支持丰富的 Swagger 注解提供了更多的功能。提供了在线调试功能方便开发者测试接口。
Swagger
特性 标准化规范 Swagger 是 OpenAPI 规范的实现之一具有广泛的支持和社区。 生态系统丰富 由于是较早的 API 文档工具有庞大的社区和丰富的插件生态系统。 强大的生态支持 支持多种语言和框架适用于各种项目。
优势
作为 OpenAPI 规范的实现与其他支持 OpenAPI 的工具和库更好地集成。有着较长时间的发展历史生态系统较为成熟。
2. 选择 Knife4j 的理由 UI 界面更友好 Knife4j 的 UI 界面相较于原生 Swagger 更加美观和易用提供了更好的用户体验。 功能扩展更丰富 Knife4j 在 Swagger 的基础上进行了功能扩展支持更多的 Swagger 注解和一些额外的扩展注解提供了更多的功能。 在线调试更方便 Knife4j 提供了在线调试和测试 API 的功能方便开发者在文档中直接进行接口测试。 社区支持良好 尽管相对于 SwaggerKnife4j 的用户规模可能较小但其社区仍然活跃能够提供一定的支持。
综合考虑上述因素选择 Knife4j 的主要理由在于其更友好的 UI 界面、丰富的功能扩展和方便的在线调试功能。然而具体选择应该根据项目需求、开发者团队的偏好以及其他因素来决定。
Knife4j中的注解说明
Knife4j 中的注解主要用于配置和描述 API 文档。这些注解帮助开发者更精确地定义 API 接口、模型类等信息以便生成详细的 API 文档。以下是一些在 Knife4j 中常用的注解及其作用
1. 控制器类相关注解
Api 注解
Api 注解用于对整个控制器类进行描述指定一些全局信息如分组、描述等。
Api(tags 示例接口, description 用于演示 Knife4j 的 API 接口)
RestController
RequestMapping(/api)
public class SampleController {// ...
}tags指定分组用于在文档中对接口进行分类展示。description对整个控制器的描述。
2. 接口方法相关注解
ApiOperation 注解
ApiOperation 注解用于对单个接口方法进行描述指定该接口的一些信息如标题、说明等。
ApiOperation(value 获取 Hello 信息, notes 这是一个示例接口返回 Hello, Knife4j!)
GetMapping(/hello)
public String getHelloMessage() {return Hello, Knife4j!;
}value接口的标题。notes接口的详细说明。
ApiParam 注解
ApiParam 注解用于对接口方法的参数进行描述指定参数的一些信息如名称、是否必须、描述等。
GetMapping(/greet)
ApiOperation(value 根据名称问候, notes 根据传入的名称返回问候语)
public String greet(ApiParam(value 姓名, required true) RequestParam String name) {return Hello, name !;
}value参数的描述。required指定参数是否是必须的。
3. 模型类相关注解
ApiModel 注解
ApiModel 注解用于对模型类进行描述指定模型的一些信息如描述、子类等。
ApiModel(description 用户信息)
public class User {// ...
}description模型的描述。
ApiModelProperty 注解
ApiModelProperty 注解用于对模型类的属性进行描述指定属性的一些信息如描述、示例值等。
public class User {ApiModelProperty(value 用户ID, example 123)private Long id;ApiModelProperty(value 用户姓名, example John Doe)private String name;// ...
}value属性的描述。example属性的示例值。
这些注解使得 Knife4j 能够生成更加详细、清晰的 API 文档。在实际应用中结合这些注解可以使 API 文档更具可读性和易用性。
实战演示
引入maven依赖
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.3/version
/dependency配置类
package fun.todoitbo.botally.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** author xiaobo*/
Configuration
EnableSwagger2
public class Knife4jConfiguration {Bean(value defaultApi2)public Docket defaultApi2() {// 设置分组名称String groupName记账API;// 创建 Docket 对象Docket docketnew Docket(DocumentationType.OAS_30).apiInfo(new ApiInfoBuilder().title(记账 API ).description(# 关于记账软件的 API).contact(new Contact(一只牛博,https://todoitbo.fun,todoitboqq.com)).version(3.0).build())// 设置分组名称.groupName(groupName).select()// 指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage(fun.todoitbo.botally.controller)).paths(PathSelectors.any()).build();return docket;}}请求vo实现
package fun.todoitbo.botally.vo;import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;import java.time.LocalDateTime;/*** 用户账单表(TbBill)实体类** author todoitbo* since 2024-01-03 13:57:52*/
Data
NoArgsConstructor
AllArgsConstructor
Builder
public class GetTbBillReqVo {ApiModelProperty(value 账单主键id)private Long id;ApiModelProperty(value 账单类别id)private Long categoryId;ApiModelProperty(value 最小金额)private Double minAmount;ApiModelProperty(value 最大金额)private Double maxAmount;ApiModelProperty(value 名称)private String name;ApiModelProperty(value 开始时间)JsonFormat(pattern yyyy-MM-dd HH:mm:ss)private LocalDateTime startTime;ApiModelProperty(value 结束时间)JsonFormat(pattern yyyy-MM-dd HH:mm:ss)private LocalDateTime endTime;ApiModelProperty(value 账单出账)private int inBill;ApiModelProperty(value 账单时间)JsonFormat(pattern yyyy-MM-dd HH:mm:ss)private LocalDateTime belongTime;}
响应VO实现
package fun.todoitbo.botally.vo;import com.fasterxml.jackson.annotation.JsonFormat;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import java.math.BigDecimal;
import java.time.LocalDateTime;/*** author todoitbo* date 2024/1/3*/
Data
public class TbBillRespVo {ApiModelProperty(value 账单ID主键)JsonSerialize(using ToStringSerializer.class)private Long id;ApiModelProperty(value 账单类别id)JsonSerialize(using ToStringSerializer.class)private Long categoryId;ApiModelProperty(value 账单时间)JsonFormat(pattern yyyy-MM-dd HH:mm:ss)private LocalDateTime billTime;ApiModelProperty(value 金额)private BigDecimal amount;ApiModelProperty(value 名称)private String name;ApiModelProperty(value 账单类别名称)private String categoryName;ApiModelProperty(value 是否收入)private int inBill;
}
controller实现
package fun.todoitbo.botally.controller;import fun.todoitbo.botally.dto.BoResult;
import fun.todoitbo.botally.service.ITbBillService;
import fun.todoitbo.botally.vo.DetailRespVo;
import fun.todoitbo.botally.vo.GetTbBillReqVo;
import fun.todoitbo.botally.vo.SaveTbBillReqVo;
import fun.todoitbo.botally.vo.TbBillRespVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;import javax.annotation.Resource;
import javax.validation.constraints.NotNull;
import java.util.List;/*** 用户账单表(TbBill)控制器** author todoitbo* since 2024-01-03 13:57:52*/
RestController
RequestMapping(value TbBill)
Api(tags 用户账单表(TbBill)控制器)
Validated
public class TbBillController {Resourceprotected ITbBillService service;PostMapping(/saveBill)ApiOperation(value 新增账单)public BoResultBoolean saveBill(Validated RequestBody SaveTbBillReqVo saveTbBillReqVo) {return BoResult.resultOk(service.saveBill(saveTbBillReqVo));}DeleteMapping(/deleteBill)ApiOperation(value 删除账单)public BoResultBoolean deleteBill(NotNull(message id不能为空) Long id) {return BoResult.resultOk(service.deleteBill(id));}GetMapping(/getBillList)ApiOperation(value 获取账单列表)public BoResultListTbBillRespVo getBillList(Validated GetTbBillReqVo getTbBillReqVo) {return BoResult.resultOk(service.getBillList(getTbBillReqVo));}GetMapping(/getDetail)ApiOperation(value 获取账单详情)public BoResultDetailRespVo getDetail() {return BoResult.resultOk(service.getDetail());}
}
效果展示图 彩蛋(报错 解决) 这个报错是因为springboot版本高由于现代浏览器和中间件对URL的敏感性增加一些场景下使用ant风格的URL匹配可能会出现问题。因此为了保证最大的兼容性和可移植性建议在Spring Boot项目中添加这个配置。 spring:mvc:pathmatch:matching-strategy: ant_path_matcher结语
希望通过这篇文章你能够更深入地了解 Knife4j 在 Spring Boot 中的应用。在文档的世界里每一刀都是为了更好地表达思想而 Knife4j 就是我们的得力助手。让我们一同投入这场文档的舞台为代码增色不少为开发带来更多的便利与乐趣。
