精雕细琢的文档体验：Spring Boot 与 Knife4j 完美交汇

news2025/1/18 10:41:39

欢迎来到我的博客，代码的世界里，每一行都是一个故事

精雕细琢的文档体验：Spring Boot 与 Knife4j 完美交汇

    • 前言
    • Knife4j 与 Swagger 的区别
      • 1. 特性与优劣势对比：
        • Knife4j：
        • Swagger：
      • 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：

特性：

  1. UI 界面美观： Knife4j 提供了一套漂亮的、易用的 UI 界面，展示了 API 文档的信息，并支持在线调试和测试。

  2. 支持多种注解： Knife4j 支持众多的 Swagger 注解，并且提供了一些额外的扩展注解，如 @ApiImplicitParams、@ApiOperationSupport 等。

  3. 在线调试： 提供了在线调试和测试 API 的功能，开发者可以直接在文档中进行接口的测试。

  4. 强大的扩展性： 支持自定义扩展，开发者可以根据需求进行定制化。

优势：

  • UI 界面美观，易用性好。
  • 支持丰富的 Swagger 注解，提供了更多的功能。
  • 提供了在线调试功能，方便开发者测试接口。
Swagger：

特性：

  1. 标准化规范： Swagger 是 OpenAPI 规范的实现之一，具有广泛的支持和社区。

  2. 生态系统丰富： 由于是较早的 API 文档工具，有庞大的社区和丰富的插件生态系统。

  3. 强大的生态支持： 支持多种语言和框架，适用于各种项目。

优势：

  • 作为 OpenAPI 规范的实现，与其他支持 OpenAPI 的工具和库更好地集成。
  • 有着较长时间的发展历史，生态系统较为成熟。

2. 选择 Knife4j 的理由：

  1. UI 界面更友好： Knife4j 的 UI 界面相较于原生 Swagger 更加美观和易用，提供了更好的用户体验。

  2. 功能扩展更丰富： Knife4j 在 Swagger 的基础上进行了功能扩展，支持更多的 Swagger 注解和一些额外的扩展注解，提供了更多的功能。

  3. 在线调试更方便： Knife4j 提供了在线调试和测试 API 的功能，方便开发者在文档中直接进行接口测试。

  4. 社区支持良好： 尽管相对于 Swagger，Knife4j 的用户规模可能较小，但其社区仍然活跃，能够提供一定的支持。

综合考虑上述因素，选择 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依赖

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>3.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 docket=new Docket(DocumentationType.OAS_30)
                .apiInfo(new ApiInfoBuilder()
                        .title("记账 API ")
                        .description("# 关于记账软件的 API")
                        .contact(new Contact("一只牛博","https://todoitbo.fun","todoitbo@qq.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 {

    @Resource
    protected ITbBillService service;

    @PostMapping("/saveBill")
    @ApiOperation(value = "新增账单")
    public BoResult<Boolean> saveBill(@Validated @RequestBody SaveTbBillReqVo saveTbBillReqVo) {
        return BoResult.resultOk(service.saveBill(saveTbBillReqVo));
    }
    @DeleteMapping("/deleteBill")
    @ApiOperation(value = "删除账单")
    public BoResult<Boolean> deleteBill(@NotNull(message = "id不能为空") Long id) {
        return BoResult.resultOk(service.deleteBill(id));
    }
    @GetMapping("/getBillList")
    @ApiOperation(value = "获取账单列表")
    public BoResult<List<TbBillRespVo>> getBillList(@Validated GetTbBillReqVo getTbBillReqVo) {
        return BoResult.resultOk(service.getBillList(getTbBillReqVo));
    }
    @GetMapping("/getDetail")
    @ApiOperation(value = "获取账单详情")
    public BoResult<DetailRespVo> getDetail() {
        return BoResult.resultOk(service.getDetail());
    }
}

效果展示图

在这里插入图片描述

彩蛋(报错 解决)

在这里插入图片描述

这个报错是因为springboot版本高，由于现代浏览器和中间件对URL的敏感性增加，一些场景下使用ant风格的URL匹配可能会出现问题。因此，为了保证最大的兼容性和可移植性，建议在Spring Boot项目中添加这个配置。

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

结语：

希望通过这篇文章，你能够更深入地了解 Knife4j 在 Spring Boot 中的应用。在文档的世界里，每一刀都是为了更好地表达思想，而 Knife4j 就是我们的得力助手。让我们一同投入这场文档的舞台，为代码增色不少，为开发带来更多的便利与乐趣。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/1442046.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

[C#]winform制作仪表盘好用的表盘控件和使用方法

[C#]winform制作仪表盘好用的表盘控件和使用方法

【仪表盘一般创建流程】 在C#中制作仪表盘文案&#xff08;通常指仪表盘上的文本、数字或指标显示&#xff09;涉及到使用图形用户界面&#xff08;GUI&#xff09;组件&#xff0c;比如Windows Forms、WPF (Windows Presentation Foundation) 或 ASP.NET 等。以下是一个使用W…
阅读更多...
美创科技与河南金融信创生态实验室签署战略合作协议

美创科技与河南金融信创生态实验室签署战略合作协议

2024年1月31日&#xff0c;由普惠通科技与河南省科学院物理所、北京交通大学、中国金融电子化集团重庆金融认证中心联合发起成立中部地区第一家金融信创生态实验室运营公司&#xff08;即河南豫科普惠通信创科技有限公司&#xff09;与杭州美创科技股份有限公司战略合作签约仪式…
阅读更多...
KtConnect 本地连接连接K8S工具

KtConnect 本地连接连接K8S工具

KT Connect简介 Kt Connect &#xff08;Kubernetes Developer Tool&#xff09;是一个阿里开源、轻量级的面向 Kubernetes 用户的开发测试环境治理辅助工具。其核心是通过建立本地到集群以及集群到本地的双向通道。 1.阿里开源&#xff0c;轻量级, 2. 安装快捷简单&#xf…
阅读更多...
Java基础常见面试题总结-集合（一）

Java基础常见面试题总结-集合（一）

常见的集合有哪些&#xff1f; Java集合类主要由两个接口Collection和Map派生出来的&#xff0c;Collection有三个子接口&#xff1a;List、Set、Queue。 Java集合框架图如下&#xff1a; List代表了有序可重复集合&#xff0c;可直接根据元素的索引来访问&#xff1b;Set代表…
阅读更多...
Linux 36.2@Jetson Orin Nano基础环境构建

Linux 36.2@Jetson Orin Nano基础环境构建

Linux 36.2Jetson Orin Nano基础环境构建 1. 源由2. 步骤2.1 安装NVIDIA Jetson Linux 36.2系统2.2 必备软件安装2.3 基本远程环境2.3.1 远程ssh登录2.3.2 samba局域网2.3.3 VNC远程登录 2.4 开发环境安装 3. 总结 1. 源由 现在流行什么&#xff0c;也跟风来么一个一篇。当然&…
阅读更多...
containerd中文翻译系列(十九)cri插件

containerd中文翻译系列(十九)cri插件

cri插件包含的内容比较多&#xff0c;阅读之前请深呼吸三次、三次、三次。 CRI 插件的架构 本小节介绍了 containerd 的 cri 插件的架构。 该插件是 Kubernetes 容器运行时接口&#xff08;CRI&#xff09; 的实现。Containerd与Kubelet在同一个节点上运行。containerd内部的…
阅读更多...
关于域名递归解析服务的问题

关于域名递归解析服务的问题

域名递归解析服务是互联网基础设施的重要组成部分&#xff0c;它允许用户通过域名来访问网站或应用程序。然而&#xff0c;在某些情况下&#xff0c;域名递归解析服务可能会出现问题&#xff0c;导致用户无法正常访问网站或应用程序。本文将探讨域名递归解析服务可能面临的问题…
阅读更多...
【C++第二阶段】运算符重载-【+】【cout】【++|--】

【C++第二阶段】运算符重载-【+】【cout】【++|--】

你好你好&#xff01; 以下内容仅为当前认识&#xff0c;可能有不足之处&#xff0c;欢迎讨论&#xff01; 文章目录 运算符重载加法运算符重载重载左移运算符递增|减运算符重载 运算符重载 加法运算符重载 What 普通的加减乘除&#xff0c;只能应付C中已给定的数据类型的运…
阅读更多...
SFML(1) | 自由落体小球

SFML(1) | 自由落体小球

SFML(1) | 自由落体小球 文章目录 SFML(1) | 自由落体小球1. 目的2. SFML 适合做图形显示的理由3. 使用 SFML - 构建阶段4. 使用 SFML - C 代码5. 运行效果6. 总结7. References 1. 目的 通过一些简单的例子&#xff08;2D小游戏的基础代码片段&#xff09;&#xff0c; 来学习…
阅读更多...
Python 小白的 Leetcode Daily Challenge 刷题计划 - 20240209（除夕）

Python 小白的 Leetcode Daily Challenge 刷题计划 - 20240209（除夕）

368. Largest Divisible Subset 难度&#xff1a;Medium 动态规划 方案还原 Yesterdays Daily Challenge can be reduced to the problem of shortest path in an unweighted graph while todays daily challenge can be reduced to the problem of longest path in an unwe…
阅读更多...
互联网加竞赛 基于深度学习的目标检测算法

互联网加竞赛 基于深度学习的目标检测算法

文章目录 1 简介2 目标检测概念3 目标分类、定位、检测示例4 传统目标检测5 两类目标检测算法5.1 相关研究5.1.1 选择性搜索5.1.2 OverFeat 5.2 基于区域提名的方法5.2.1 R-CNN5.2.2 SPP-net5.2.3 Fast R-CNN 5.3 端到端的方法YOLOSSD 6 人体检测结果7 最后 1 简介 &#x1f5…
阅读更多...
害怕跟别人进行社交，怎么办？

害怕跟别人进行社交，怎么办？

前几天&#xff0c;跟一位朋友&#xff0c;小聚了一下。 这位朋友&#xff0c;在一家大型 IT 公司里当技术主管。收入不低&#xff0c;烟酒不沾&#xff0c;常常健身&#xff0c;外型不错&#xff0c;为人也踏实可靠。除了有一点技术宅的死板之外&#xff0c;可以说是非常理想的…
阅读更多...
小项目：蓝牙模块点亮RGB三色灯

小项目：蓝牙模块点亮RGB三色灯

在之前的教程中&#xff0c;我们学习了蓝牙模块的原理&#xff0c;并动手写了驱动&#xff0c;实现了串口的接收和发送。本次我们就来教大家如何使用蓝牙串口控制灯。这是一个简单的示例&#xff0c;展示了如何将蓝牙通信与硬件控制相结合&#xff0c;实现远程控制的功能。你也…
阅读更多...
微软Windows生态是怎么打造成功的？

微软Windows生态是怎么打造成功的？

&#xff08;1&#xff09;2015年Windows10&#xff1a;兼容性 我不得不再次佩服一下微软&#xff0c;Windows10是2015年出品的&#xff0c;但是仍然能正常运行绝大多数的Windows95软件&#xff0c;不用做任何的适配修改&#xff0c;连重新编译都不用&#xff0c;运行照样正常。…
阅读更多...
AcWing 1224 交换瓶子（简单图论）

AcWing 1224 交换瓶子（简单图论）

[题目概述] 有 N 个瓶子&#xff0c;编号 1∼N&#xff0c;放在架子上。 比如有 5 个瓶子&#xff1a; 2 1 3 5 4 要求每次拿起 2 个瓶子&#xff0c;交换它们的位置。 经过若干次后&#xff0c;使得瓶子的序号为&#xff1a; 1 2 3 4 5 对于这么简单的情况&#xff0c;显然&a…
阅读更多...
mysql8.0 正值表达式Regular expressions （sample database classicmodels _No.5）

mysql8.0 正值表达式Regular expressions （sample database classicmodels _No.5）

mysql8.0 正值表达式Regular expressions 准备工作&#xff0c;可以去下载 classicmodels 数据库资源如下 [ 点击&#xff1a;classicmodels] (https://download.csdn.net/download/tomxjc/88685970) 也可以去我的博客资源下载 https://download.csdn.net/download/tomxjc/8…
阅读更多...
Eclipse导入maven项目或者创建maven项目时,报错Could not calculate build plan: Plugin

Eclipse导入maven项目或者创建maven项目时,报错Could not calculate build plan: Plugin

问题&#xff1a;Eclipse导入maven项目或者创建maven项目时,报错Could not calculate build plan: Plugin 1.上述问题大概是项目不能加载此maven插件&#xff0c;在pom文件中添加依赖项 <dependency><groupId>org.apache.maven.plugins</groupId><artifa…
阅读更多...
JetpackCompose之状态管理

JetpackCompose之状态管理

JetPack Compose系列&#xff08;13&#xff09;—状态管理 State 即&#xff0c;状态。官方的解释是&#xff1a; State in an application is any value that can change over time. And ****event can notify a part of a program that something has happened. 可以这样…
阅读更多...
发廊理发店微信小程序展示下单前端静态模板源码

发廊理发店微信小程序展示下单前端静态模板源码

模板描述&#xff1a;剪发小程序前端源码&#xff0c;一共五个页面&#xff0c;包括店铺、理发师、订单、我的等页面 注&#xff1a;该源码是前端静态模板源码&#xff0c;没有后台和API接口
阅读更多...
代码随想录算法训练营第四十六天（动态规划篇）|01背包（滚动数组方法）

代码随想录算法训练营第四十六天（动态规划篇）|01背包（滚动数组方法）

01背包&#xff08;滚动数组方法&#xff09; 学习资料&#xff1a;代码随想录 (programmercarl.com) 题目链接&#xff08;和上次一样&#xff09;&#xff1a;题目页面 (kamacoder.com) 思路 使用一维滚动数组代替二维数组。二维数组的解法记录在&#xff1a;代码随想录算…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023