spring-boot3.x整合Swagger 3 (OpenAPI 3) +knife4j

1.简介

        OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后，Swagger规范正式更名为OpenAPI规范，并且根据OpenAPI规范的版本号进行了更新。因此，Swagger 3.0对应的就是OpenAPI 3.0版本，它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比，Swagger 3.0更加强调对RESTful API的支持和规范化，提供了更丰富和灵活的定义方式，并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。

1.1 Open API

        OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。

OpenAPI 3 Library for spring-boot (springdoc.org)

1.2 Swagger

        swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者

1.3 SpringFox

SpringFox 是一个成熟且广泛使用的库，它允许你通过注解描述 API 并生成符合 OpenAPI 规范（原 Swagger 规范）的文档。SpringFox 支持 Swagger 2.0 及其后继者 OpenAPI 3.0。

特点:

  • 支持 Swagger 2.0 和 OpenAPI 3.0。
  • 通过使用 Swagger 注解（如 @Api, @ApiOperation, @ApiModel, @ApiModelProperty 等）来描述 API。
  • 提供了多种方式来自定义文档，包括通过代码或配置文件。
  • 可以通过扫描类路径中的控制器类自动生成文档。
  • 更新频率较低，最近几年维护活动减少。

1.4 SpringDoc

OpenAPI 3 Library for spring-boot (springdoc.org)

SpringDoc 是一个相对较新的替代方案，它专为 OpenAPI 3.0 设计，提供了对最新 OpenAPI 规范的全面支持。

特点:

  • 主要关注 OpenAPI 3.0，对 OpenAPI 3.0 的支持更全面。
  • 使用更简洁的注解（如 @Tag, @Operation, @Parameter 等）来描述 API。
  • 更好的支持 Spring WebFlux，适合现代的响应式编程模型。
  • 更频繁的更新和活跃的社区支持。
  • 与 Spring Boot 的集成更加紧密，可以通过 Spring Boot 的自动配置特性简化设置过程。

1.5 Knife4j

        Knife4jInsight(简单、方便的OpenAPI接口文档私有化聚合平台),地址：http://knife4j.neticon-default.png?t=N7T8http://knife4j.net/

1.6 Swagger 3 (OpenAPI 3) 与swagger 2 区别

1.7 Swagger 3 (OpenAPI 3)注解详细介绍

（1）基本信息注解描述位置属性

@OpenAPIDefinition

用于定义整个 API 文档的基本信息。类、接口
  • info：指定 @Info 注解的对象，用于描述 API 文档的基本信息。

@Info

用于定义 API 文档的基本信息类、接口。
  • title：API 的标题。
  • description：API 的描述。
  • version：API 的版本号。
  • termsOfService：服务条款的 URL。
  • contact：指定 @Contact 注解的对象，用于描述联系人信息。
  • license：指定 @License 注解的对象，用于描述许可证信息。

@Contact

用于定义 API 文档中的联系人信息。类、接口
  • name：联系人的名称。
  • url：联系人的网址。
  • email：联系人的电子邮件地址。

@License

用于定义 API 文档中的许可证信息类、接口。
  • name：许可证的名称。
  • url：许可证的网址。
（2）分组注解描述位置属性

@Tag

用于给 API 分组，用途类似于为 API 文档添加标签。方法、类、接口
  • name：分组的名称。
（3）请求方法注解描述位置属性

@Operation

用于描述 API 的操作。方法。
  • summary：操作的摘要信息。
  • description：操作的详细描述。
  • tags：指定 @Tag 注解的对象数组，用于将操作归类到特定的分组。
  • parameters：指定 @Parameter 注解的对象数组，用于描述操作的输入参数。
  • responses：指定 @ApiResponse 注解的对象数组，用于描述操作的响应结果。
  • requestBody：指定 @RequestBody 注解的对象，用于描述操作的请求体。

@Parameter

用于描述操作的输入参数。方法
  • name：参数的名称。
  • in：参数的位置，可以是 path、query、header、cookie 中的一种。
  • description：参数的描述。
  • required：参数是否必需，默认为 false。

  • schema：指定 @Schema 注解的对象，用于描述参数的数据类型。

@RequestBody

用于描述操作的请求体方法
  • required：请求体是否必需，默认为 false。
  • content：指定 @Content 注解的对象数组，用于描述请求体的内容。

@ApiResponse

用于描述操作的响应结果方法
  • responseCode：响应的状态码。
  • description：响应的描述。
  • content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

用于描述请求体或响应的内容方法。
  • mediaType：内容的媒体类型。
  • schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

用于描述数据模型的属性。方法、类、接口。
  • title：数据模型的标题。
  • description：数据模型的描述。
  • type：数据模型的类型。
  • format：数据模型的格式。
（4）路径注解描述位置属性

@Path

用于定义路径参数。方法
  • value：路径参数的名称。

@PathVariable

用于描述路径参数。方法的参数
  • value：路径参数的名称。

@RequestParam

用于描述查询参数。方法的参数。
  • value：查询参数的名称。
  • required：查询参数是否必需，默认为 false

@RequestBody

用于描述请求体。方法的参数
（5） 响应注解描述位置属性

@ApiResponse

用于描述响应结果。方法。
  • responseCode：响应的状态码。
  • description：响应的描述。
  • content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

用于描述响应结果的内容方法
  • mediaType：内容的媒体类型。
  • schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

用于描述数据模型的属性。方法、类、接口。
  • title：数据模型的标题。
  • description：数据模型的描述。
  • type：数据模型的类型。
  • format：数据模型的格式。

 2. 配置Knife4j

2.1 添加依赖

        因为Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突。这里直接使用Knife4j

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

2.2 添加配置类

package com.zsh.test.swagger3test.config;import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.configuration.SpringDocConfiguration;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.boot.autoconfigure.AutoConfigureBefore;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import java.util.Collections;/**Knife4j整合swagger3* @author ZhaoShuhao* @data 2024/7/21 11:06*/
@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI springShopOpenApi() {return new OpenAPI()// 接口文档标题.info(new Info().title("swagger3")// 接口文档简介.description("这是基于Knife4j OpenApi3的测试接口文档")// 接口文档版本.version("1.0版本")// 开发者联系方式.contact(new Contact().name("zsh").email("1401969521@qq.com")));}
}

2.3 yml配置

springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: 'zsh'paths-to-match: '/**'#生成文档所需的扫包路径，一般为启动类目录packages-to-scan: com.zsh.test.swagger3test#knife4j配置
knife4j:#是否启用增强设置enable: true#开启生产环境屏蔽production: false#是否启用登录认证basic:enable: trueusername: adminpassword: 123456setting:language: zh_cnenable-version: trueenable-swagger-models: trueswagger-model-name: 用户模块

2.4 运行结果

路径：http://localhost:8080/doc.html

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

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

相关文章

Unity判断鼠标是否在UI上

Unity判断鼠标是否在UI上

Unity判断鼠标是否在UI上 下值等于true表示在UI上 EventSystem.current.IsPointerOverGameObject()可用来判断滚轮滑动缩放视角功能&#xff0c;在UI上滑动滚轮视角不缩放&#xff0c;反之缩放。
阅读更多...
Python开发日常总结

Python开发日常总结

1、命令总结 1.1 conda创建、激活、退出虚拟环境 conda create --name myenv python3.8 # 创建 conda create --name myenv python3.9 # 激活 conda activate myenv # 退出 conda deactivate
阅读更多...
产品系统的UI暗色系和浅色系模式切换是符合人体视觉工程学的设计

产品系统的UI暗色系和浅色系模式切换是符合人体视觉工程学的设计

视觉革命&#xff1a;UI设计中的暗夜与黎明 UI设计如同夜空中最亮的星辰&#xff0c;引领着用户穿梭于信息的海洋。而今&#xff0c;一场视觉革命正在悄然上演&#xff0c;它关乎于我们的眼睛&#xff0c;关乎于我们的体验——那就是产品系统的UI暗色系和浅色系模式的切换。如…
阅读更多...
手写一个JVM自定义类加载器

手写一个JVM自定义类加载器

1. 自定义类加载器的意义 隔离加载类&#xff1a;在某些框架内进行中间件与应用的模块隔离&#xff0c;把类加载到不同的环境。比如&#xff1a;阿里内某容器框架通过自定义类加载器确保应用中依赖的jar包不会影响到中间件运行时使用的jar包。再比如&#xff1a;Tomcat这类Web…
阅读更多...
Android lmkd机制详解

Android lmkd机制详解

目录 一、lmkd介绍 二、lmkd实现原理 2.1 工作原理图 2.2 初始化 2.3 oom_adj获取 2.4 监听psi事件及处理 2.5 进程选取与查杀 2.5.1 进程选取 2.5.2 进程查杀 三、关键系统属性 四、核心数据结构 五、代码时序 一、lmkd介绍 Android lmkd采用epoll方式监听linux内…
阅读更多...
SpringBoot整合阿里云短信业务

SpringBoot整合阿里云短信业务

详细介绍SpringBoot整合阿里云短信服务的每一步过程&#xff0c;同时会将验证码存放到Redis中并设置过期时间&#xff0c;尽量保证实战的同时也让没做过的好兄弟也能实现发短信的功能~ 1. 注册阿里云账号和创建Access Key 首先&#xff0c;你需要注册一个阿里云账号&#xff0…
阅读更多...
Flutter 使用 url_launcher的canLaunchUrl() 方法总是返回false错误

Flutter 使用 url_launcher的canLaunchUrl() 方法总是返回false错误

Flutter 使用 url_launcher的canLaunchUrl() 方法总是返回false错误 众所周知&#xff0c;我们一般使用url_launcher来打开各种应用&#xff0c;网页&#xff0c;手机应用等.... 但是最近发现Flutter的canLaunchUrl()方法总是返回false&#xff0c;这是为什么呢&#xff1f; …
阅读更多...
Qt 实战（3）数据类型 | 3.2、QVariant

Qt 实战（3）数据类型 | 3.2、QVariant

文章目录 一、QVariant1、存储数据1.1、存储Qt内置数据1.2、存储自定义数据 2、获取数据3、判断数据类型4、清空数据5、总结 前言&#xff1a; QVariant是Qt框架中一个非常强大且灵活的类&#xff0c;它提供了一种通用的方式来存储和转换几乎任何类型的数据。无论是基本数据类型…
阅读更多...
【JavaEE初阶】Thread类及常见方法

【JavaEE初阶】Thread类及常见方法

目录 &#x1f4d5; Thread类的概念 &#x1f4d5; Thread 的常见构造方法 &#x1f4d5; Thread 的几个常见属性 &#x1f4d5; start()-启动一个线程 &#x1f4d5; 中断一个线程 &#x1f6a9; 实例一 &#x1f6a9; 实例二 &#x1f6a9; 实例三 &#x1f4d5; jo…
阅读更多...
Android中的usescleartexttraffic属性详解

Android中的usescleartexttraffic属性详解

Android中的usescleartexttraffic属性详解 usesCleartextTraffic 是 Android 应用程序开发中的一个重要配置选项&#xff0c;用于控制应用程序是否允许通过不加密的 HTTP 协议进行网络通信。在 Android 应用的开发过程中&#xff0c;正确地配置 usesCleartextTraffic 对于保护用…
阅读更多...
昇思MindSpore学习入门-数据处理管道支持python对象

昇思MindSpore学习入门-数据处理管道支持python对象

数据处理管道中的特定操作&#xff08;如自定义数据集GeneratorDataset、自定义map增强操作、自定义batch(per_batch_map...)&#xff09;支持任意Python类型对象作为输入。为了支持此特性&#xff0c;数据管道使用了Python(dict)字典去管理不同类型的对象。与其他类型相比&…
阅读更多...
康康近期的慢SQL（oracle vs 达梦）

康康近期的慢SQL（oracle vs 达梦）

近期执行的sql&#xff0c;哪些比较慢&#xff1f; 或者健康检查时搂一眼状态 oracle&#xff1a; --最近3天内的慢sql set lines 200 pages 100 col txt for a65 col sql_id for a13 select a.sql_id,a.cnt,a.pctload,b.sql_text txt from (select * from (select sql_id,co…
阅读更多...
Nvm和Npm和Pm2的关系和使用说明

Nvm和Npm和Pm2的关系和使用说明

一、三者关系说明 nvm、npm 和 pm2 在 Node.js 生态系统中扮演着不同的角色&#xff0c;但它们之间存在一定的关联。下面是每个工具的作用以及它们之间的关系&#xff1a;1. nvm (Node Version Manager)• nvm 是一个用于管理多个 Node.js 版本的工具。它允许用户在不同的项目…
阅读更多...
基于微信小程序的自习室选座系统/基于Java的自习室选座系统/自习室管理系统的设计与实现

基于微信小程序的自习室选座系统/基于Java的自习室选座系统/自习室管理系统的设计与实现

获取源码联系方式请查看文章结尾&#x1f345; 摘要 自习室选座是学校针对用户必不可少的一个部分。在学校的整个过程中&#xff0c;学生担负着最重要的角色。为满足如今日益复杂的管理需求&#xff0c;各类微信小程序自习室选座也在不断改进。本课题所设计的小程序自习室选座系…
阅读更多...
【C#】Visual Studio2022打包依赖第三方库的winForm程序为exe

【C#】Visual Studio2022打包依赖第三方库的winForm程序为exe

0.简介 IDE&#xff1a;VS2022 平台&#xff1a;C# .NetFramework4.7.2 WinForm界面 有GDAL、EEplus第三方库的依赖&#xff0c;所以在其他未安装环境的电脑中功能无法使用。 1. 安装 1.1 运行文件输出 在VS扩展中选择管理扩展&#xff0c;安装&#xff1a;Microsoft Visua…
阅读更多...
SpringBoot上传超大文件导致OOM，完美问题解决办法

SpringBoot上传超大文件导致OOM，完美问题解决办法

问题描述 报错： Caused by: java.lang.OutOfMemoryError at java.io.ByteArrayOutputStream.hugeCapacity(ByteArrayOutputStream.java:123) ~[?:1.8.0_381] at java.io.ByteArrayOutputStream.grow(ByteArrayOutputStream.java:117) ~[?:1.8.0_381] at java.…
阅读更多...
Android 更换applicationId 后 微信没有回调

Android 更换applicationId 后 微信没有回调

1、解决办法&#xff08;代码如下&#xff09;&#xff1a; 使用 <activity-alias>: 这是一个用于定义活动别名的元素。活动别名可以让您为已经定义的活动提供一个别名&#xff0c;从而可以通过别名启动原来的活动。 <activityandroid:name".wxapi.WXEntryActiv…
阅读更多...
ES6 class 类

ES6 class 类

普通使用原型添加方法 function Animal(name) {this.name name; }Animal.prototype.speak function() {console.log(this.name makes a noise.); };function Dog(name) {Animal.call(this, name); }Dog.prototype Object.create(Animal.prototype); Dog.prototype.constr…
阅读更多...
MQTTX连接华为云IoTDA

MQTTX连接华为云IoTDA

目录 华为IoTDA平台 MQTTX连接参数的设置 物模型的构建 属性上报 基本数据格式 时戳 我以前上课都是用巴法云服务器来演示MQTT的&#xff0c;前几天因为测试工业互联网关使用了华为的IoTDA&#xff0c;觉得也不算太复杂&#xff0c;今天尝试用MQTTX连接华为云&#xff0c…
阅读更多...
【ARM】MDK-STM32g0xx.h文件与Define规则记录

【ARM】MDK-STM32g0xx.h文件与Define规则记录

【更多软件使用问题请点击亿道电子官方网站】 1、 文档目标 记录问题STM32g0xx.h等有关ST的可读文件&#xff0c;尽量勿修改文件格式及对其代码进行添加和删减&#xff0c;记录查找问题的过程中的疑惑&#xff0c;并如何给予客户正确的回复&#xff0c;帮助销售完成验收&…
阅读更多...
最新文章

Copyright @ 2022~2023