如何区别在Spring Boot 2 和 Spring Boot 3 中使用 Knife4j:集成与配置指南

在现代的 Web 开发中,API 文档是不可或缺的一部分。Knife4j 是基于 Swagger 的增强工具,它不仅提供了更友好的 API 文档界面,还支持更多实用的功能,如离线文档导出、全局参数配置等。本文将详细介绍如何在 Spring Boot 2Spring Boot 3 中集成 Knife4j,并讲解其常用配置和注解的使用方法。


一、Knife4j 简介

Knife4j(原名 Swagger-Bootstrap-UI)是 Swagger 的增强版,提供了以下核心功能:

  1. 更友好的界面:美观、简洁的 API 文档展示。
  2. 增强功能:支持离线文档导出、全局参数、调试增强等。
  3. 兼容性:支持 Swagger 2 和 OpenAPI 3 规范。
  4. 易用性:通过简单配置即可快速集成。

二、Spring Boot 2 中使用 Knife4j

1. 依赖引入

pom.xml 中添加 Knife4j 的依赖:

<XML>

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

2. 配置 Swagger

创建一个配置类,定义 Swagger 的基本信息:

<JAVA>

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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 扫描的包路径.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Knife4j Demo API").description("Spring Boot 2 with Knife4j Example").version("1.0").build();}
}

3. 编写 Controller

创建一个示例 Controller,用于生成 API 文档:

<JAVA>

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/api")
@Api(tags = "示例模块")
public class DemoController {@GetMapping("/hello")@ApiOperation(value = "示例接口", notes = "返回一个简单的问候语")public String hello() {return "Hello, Knife4j!";}
}

4. 访问 Knife4j 文档

启动项目,访问以下 URL:

  • Knife4j 文档页面:http://localhost:8080/doc.html
  • Swagger JSON 文档:http://localhost:8080/v2/api-docs

三、Spring Boot 3 中使用 Knife4j

1. 依赖引入

Spring Boot 3 使用 Jakarta EE 9+,因此需要引入 jakarta 版本的 Knife4j 依赖:

<XML>

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.2.0</version>
</dependency>

2. 配置 OpenAPI

创建一个配置类,定义 OpenAPI 的基本信息:

<JAVA>

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class Knife4jConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Knife4j Demo API").version("1.0").description("Spring Boot 3 with Knife4j Example"));}
}

3. 编写 Controller

创建一个示例 Controller,用于生成 API 文档:

<JAVA>

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/api")
@Tag(name = "示例模块", description = "示例模块 API")
public class DemoController {@GetMapping("/hello")@Operation(summary = "示例接口", description = "返回一个简单的问候语")public String hello() {return "Hello, Knife4j!";}
}

4. 访问 Knife4j 文档

启动项目,访问以下 URL:

  • Knife4j 文档页面:http://localhost:8080/doc.html
  • OpenAPI 3 JSON 文档:http://localhost:8080/v3/api-docs

四、Knife4j 常用配置

1. 配置启用 Knife4j

application.yml 中配置:

<YAML>

knife4j:enable: true # 启用 Knife4jsetting:language: zh-CN # 界面语言为中文enable-swagger-models: true # 显示 Modelsenable-default-params: true # 启用默认参数

2. 离线文档导出

Knife4j 支持将文档导出为 Markdown、HTML 或 Word 格式:

  1. 访问 Knife4j 文档页面。
  2. 点击右上角的“离线文档”按钮。
  3. 选择导出格式并下载。

3. 全局参数

在 Swagger 配置类中添加全局参数:

<JAVA>

import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityScheme;@Bean
public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).securitySchemes(Collections.singletonList(new ApiKey("Authorization", "Authorization", "header"))).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();
}

五、Knife4j 常用注解

1. 类级别注解

  • @Api(Swagger 2)(springboot2使用注解):用于标识 API 模块的名称。

    <JAVA>

    @Api(tags = "示例模块")
  • @Tag(OpenAPI 3 (springboot3使用注解)):用于标识 API 模块的名称。

    <JAVA>

    @Tag(name = "示例模块", description = "示例模块 API")

2. 方法级别注解

  • @ApiOperation(Swagger 2)(springboot2使用注解):用于描述 API 接口的详细信息。

    <JAVA>

    @ApiOperation(value = "示例接口", notes = "返回一个简单的问候语")
  • @Operation(OpenAPI 3)(springboot3使用注解):用于描述 API 接口的详细信息。

    <JAVA>

    @Operation(summary = "示例接口", description = "返回一个简单的问候语")

3. 参数级别注解

  • @ApiParam(Swagger 2)(springboot2使用注解):用于描述 API 参数。

    <JAVA>

    @ApiParam(name = "name", value = "用户名称", required = true)
  • @Parameter(OpenAPI 3)(springboot3使用注解):用于描述 API 参数。

    <JAVA>

    @Parameter(name = "name", description = "用户名称", required = true)

六、总结

Knife4j 是 Swagger 的增强版,适合在 Spring Boot 项目中生成美观、功能强大的 API 文档。本文详细介绍了如何在 Spring Boot 2 和 Spring Boot 3 中集成 Knife4j,并讲解了常用配置和注解的使用方法。

如果你正在为 API 文档的生成和展示而烦恼,不妨试试 Knife4j,它会为你的开发工作带来极大的便利!😊


参考资源

  • Knife4j 官方文档
  • Swagger 官方文档

希望这篇博客对你有所帮助,欢迎在评论区分享你的使用体验或提出问题!🚀

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

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

pagehelper 分页插件使用说明

pom.xml&#xff1a;pageHelper坐标 <!--pageHelper坐标--><dependency><groupId>com.github.pagehelper</groupId><artifactId>pagehelper-spring-boot-starter</artifactId><version>1.4.6</version></dependency> 分…

C++可变参数

可变参数C风格的可变参数C风格可变参数的使用 C11可变参数模板递归展开参数包参数列表展开折叠表达式 STL中的emplace插入接口 可变参数 C风格的可变参数 可变参数是一种语言特性&#xff0c;可以在函数声明中使用省略号...来表示函数接受可变数量的参数。 例如典型的printf…

数据库的操作,以及sql之DML

首先&#xff0c;创建表以及插入数据 create table t_text(id int primary key auto_increment,name varchar(20) unique not null,gender char(5) not null check(gender in ("男","女")),deed varchar(255) not null default "事例不详"); in…

vue2前端日志数据存储(indexedD)自动清理3天前的数据

前言&#xff1a;关于Dexie.js这个前端本地数据库&#xff0c;如何使用IndexedDB来存储数据&#xff0c;并且设置到期自动清理的机制。首先&#xff0c;我需要回忆一下Dexie.js的基本用法&#xff0c;以及IndexedDB的特性。IndexedDB是浏览器中的一种非关系型数据库&#xff0c…

【MySQL篇】索引特性,索引的工作原理以及索引的创建与管理

目录 一&#xff0c;初识索引 二&#xff0c;MySQL与磁盘交互的基本单位 三&#xff0c;MySQL中数据文件的特性 四&#xff0c;理解page和索引 五&#xff0c;聚簇索引和非聚簇索引 六&#xff0c;索引操作 查询索引 创建主键索引 唯一索引的创建 普通索引的创建 全文…

springboot项目启动常见的问题以及配置以及一些使用技巧

1.配置仓库 这里要把xml文件从国外的镜像源改成国内的镜像源。改镜像源可以查看这篇文章 点击查看 2.更改文件类型 方法一&#xff1a;右键文件找到Mark Dircetory as可以更改文件类型 方法二&#xff1a; 3.springboot本地Maven仓库的位置 4.pom.xml文件报红错误怎么办 这…

【初探数据结构】二叉树的顺序结构——堆的实现详解(上下调整算法的时间复杂度分析)

&#x1f4ac; 欢迎讨论&#xff1a;在阅读过程中有任何疑问&#xff0c;欢迎在评论区留言&#xff0c;我们一起交流学习&#xff01; &#x1f44d; 点赞、收藏与分享&#xff1a;如果你觉得这篇文章对你有帮助&#xff0c;记得点赞、收藏&#xff0c;并分享给更多对数据结构感…

流量分析2

一&#xff0c;webshell流量 [GKCTF 2021]签到 先看协议分级&#xff0c;大部分是tcp&#xff0c;里面有http的基于的行文本数据占了很大的比重&#xff0c;看看里面有什么 过滤http的流量 点击一条流量&#xff0c;里面的内容进去后面有基于行的文本数据&#xff0c; 先解he…

头歌实践教学平台--【数据库概论】--SQL

一、表结构与完整性约束的修改(ALTER) 1.修改表名 USE TestDb1; alter table your_table rename TO my_table; 2.添加与删除字段 #语句1&#xff1a;删除表orderDetail中的列orderDate alter table orderDetail drop orderDate; #语句2&#xff1a;添加列unitPrice alter t…

在 React 中,组件之间传递变量的常见方法

目录 1. **通过 Props 传递数据**2. **通过回调函数传递数据**3. **通过 Context API 传递数据**4. **通过 Redux 管理全局状态**5. **通过事件总线&#xff08;如 Node.js 的 EventEmitter&#xff09;**6. **通过 Local Storage / Session Storage**7. **通过 URL 查询参数传…

Redis + 布隆过滤器解决缓存穿透问题

Redis 布隆过滤器解决缓存穿透问题 1. Redis 布隆过滤器解决缓存穿透问题 &#x1f4cc; 什么是缓存穿透&#xff1f; 缓存穿透指的是查询的数据既不在缓存&#xff0c;也不在数据库&#xff0c;导致每次查询都直接访问数据库&#xff0c;增加数据库压力。 例如&#xff1…

Vue动态添加或删除DOM元素:购物车实例

Vue 指令系列文章: 《Vue插值:双大括号标签、v-text、v-html、v-bind 指令》 《Vue指令:v-cloak、v-once、v-pre 指令》 《Vue条件判断:v-if、v-else、v-else-if、v-show 指令》 《Vue循环遍历:v-for 指令》 《Vue事件处理:v-on 指令》 《Vue表单元素绑定:v-model 指令》…

vue h5实现车牌号输入框

哈喽&#xff0c;大家好&#xff0c;最近鹏仔开发的项目是学校校内车辆超速方面的统计检测方面的系统&#xff0c;在开发过程中发现有个小功能&#xff0c;就是用户移动端添加车牌号&#xff0c;刚开始想着就一个输入框&#xff0c;提交时正则效验一下格式就行&#xff0c;最后…

硬件基础(5):(3)二极管的应用

文章目录 [toc]1. **整流电路****功能**&#xff1a;**工作原理**&#xff1a;**应用实例**&#xff1a;电路组成&#xff1a;整流过程&#xff1a;电路的应用&#xff1a; 2. **稳压电路****功能**&#xff1a;**工作原理**&#xff1a;**应用实例**&#xff1a;电路组成及功能…

Wireshark网络抓包分析使用详解

序言 之前学计网还有前几天备考华为 ICT 网络赛道时都有了解认识 Wireshark&#xff0c;但一直没怎么专门去用过&#xff0c;也没去系统学习过&#xff0c;就想趁着备考的网络相关知识还没忘光&#xff0c;先来系统学下整理点笔记~ 什么是抓包&#xff1f;抓包就是将网络传输…

安心联车辆管理平台源码价值分析

安心联车辆管理平台源码的价值可从技术特性、功能覆盖、市场适配性、扩展潜力及商业化支持等多个维度进行分析。以下结合实际应用进行详细解读&#xff1a; 一、技术架构与开发优势 主流技术栈与高性能架构 源码采用成熟的前后端分离架构&#xff0c;后端基于Java技术&#xff…

【操作系统】Docker如何使用-续

文章目录 1、概述2、巩固知识2.1、基础命令2.2、容器管理2.3、镜像管理2.4、网络管理2.5、Compose 3、常用命令 1、概述 在使用Docker的过程中&#xff0c;掌握常用的命令是至关重要的。然而&#xff0c;随着时间的推移&#xff0c;我们可能会遗忘一些关键的命令或对其用法变得…

ElementUI el-menu导航开启vue-router模式

有没有小伙伴遇到这么一种情况&#xff1a;ElementUI el-menu导航中&#xff0c;开启vue-router 的模式后&#xff0c;点击触发事件而不进行路由跳转&#xff1f; 别慌&#xff01;下面直接说解决方案&#xff1a; 借助路由守卫进行判断 给el-menu绑定切换事件&#xff0c;给…

【leetcode hot 100 17】电话号码的字母组合

分析&#xff1a;当设计关键字“所有组合”时&#xff0c;要考虑深度优先遍历、广度优先遍历&#xff08;层次遍历&#xff09;&#xff0c;其中&#xff1a; 深度优先搜索&#xff1a; 自顶向下的递归实现深搜定义子问题在当前递归层结合子问题结果解决原问题 广度优先搜索 利…

Vue 2 探秘:visible 和 append-to-body 是谁的小秘密?

&#x1f680; Vue 2 探秘&#xff1a;visible 和 append-to-body 是谁的小秘密&#xff1f;&#x1f914; 父组件&#xff1a;identify-list.vue子组件&#xff1a;fake-clue-list.vue 嘿&#xff0c;各位前端探险家&#xff01;&#x1f44b; 今天我们要在 Vue 2 的代码丛林…