文章目录
一：前言1：Swagger发展史2：Swagger其它介绍3：SpringFox工具（不推荐）4：SpringDoc工具（推荐）二：SpringBoot集成Open API 3.0（Swagger3.0）1：引入Maven依赖2：配置SwaggerOpenApiConfig（配置类方式）3：配置SwaggerOpenApiConfig（注解方式）4：配置API接口信息（注解，重要）5：配置API接口信息（定义类方式，不推荐）6：权限认证方式三：SpringBoot集成Open API3.0具体运行效果
回到目录 ↑↑↑一：前言
Swagger 是一个 RESTful API 的开源框架，它的主要目的是帮助开发者设计、构建、文档化和测试 Web API。Swagger 的核心思想是通过定义和描述 API 的规范、结构和交互方式，以提高 API 的可读性、可靠性和易用性，同时降低 API 开发的难度和开发者之间的沟通成本。
这里我采用了Swagger3.0（Open API 3.0）的方式集成到SpringBoot。springfox-boot-start和springfox-swagger2都是基于Swagger2.x的。这里将介绍springdoc-openapi-ui，它是SpringBoot基于Open API 3.0（Swagger3.0）
有兴趣的可以看看第一章介绍，若直接上手看第二章集成Swagger3.0
1：Swagger发展史
Swagger它最初由Tony Tam在2011年创建，并在之后被SmartBear Software公司收购。在过去几年中，Swagger经历了许多重大的更新和变化，
其发展史大概可以分为以下几个阶段：
①：Swagger 1.x 阶段（2011-2014年）
Swagger最初是一个简单的API文档生成工具，通过对JAX-RS和Jersey注解的支持自动生成API文档，使得API文档的维护变得更加容易。
在这个阶段，Swagger还没有完全成熟，只能支持基本的API描述和文档生成。
②：Swagger 2.x 阶段（2014-2017年）
在Swagger 2.x阶段，Swagger发生了重大变化。它不再仅仅是一个文档生成工具，而是一个完整的API开发和管理平台。Swagger 2.x加
入了强大的注解支持，可以描述API的细节信息，如请求参数、返回类型等，以及定义RESTful API的元数据，如API描述、标签等。
此外，Swagger 2.x还引入了OpenAPI规范，在API定义方面有了更严格的标准和规则。
③：OpenAPI 阶段（2017-至今）（也被称为Swagger 3.x）
在2017年，Swagger 2.x的规范成为了Linux基金会旗下的OpenAPI规范。这标志着Swagger从一款工具演变成为了一个开放且标准的API
定义框架。OpenAPI规范不仅继承了Swagger 2.x的特性，还提供了更加全面和严格的API定义规范，并且扩展了对非RESTful API的支持
随着OpenAPI规范的普及，越来越多的API开发者开始使用Swagger/OpenAPI来开发、测试和文档化他们的RESTful API。
所以，随着Linux基金会旗下的OpenAPI收购了Swagger2.x后对其进行了更严格的规范，又进行了各种优化，
所以我们也可以称OpenAPI是一个全新的Swagger3.x，因为OpenAPI对其作了更多的优化和规范。
除了上述几个主要阶段之外，还有一些其他重要的事件和版本，如Swagger UI、Swagger Codegen、SwaggerHub等等。
这些工具和服务进一步扩展了Swagger的功能，使其//代码效果参考：http://hnjlyzjd.com/hw/wz_24651.html
成为了一个更加完整、强大和易于使用的API定义和管理平台。2：Swagger其它介绍
其实OpenAPI规范（也称为 Swagger 3.x 规范）是一种用于描述RESTful API的标准化格式，它定义了如何描述API的基本信息、结构、参数、响应等方面的规范。OpenAPI规范以机器可读的方式定义了RESTful API的结构和特征，支持自动生成文档、客户端与服务端代码、Mock Server和测试工具等。
OpenAPI规范最初由开发Swagger的团队在2010年推出，从Swagger 2.0开始，Swagger规范被正式更名为OpenAPI规范，并得到了许多社区的支持和贡献。OpenAPI规范采用JSON或YAML格式编写，并支持多种数据类型，可以描述API的基本信息、路径、HTTP方法、参数、响应等各种细节。通过遵循OpenAPI规范，开发者可以快速定义和构建RESTful API，并且可以生成相应的文档和代码来帮助他们更快地开发与测试API。同时，OpenAPI规范还可以促进不同系统之间的交互和集成，因为根据规范定义的API可以被多个客户端程序和服务端程序所理解和使用。
OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后，Swagger规范正式更名为OpenAPI规范，并且根据OpenAPI规范的版本号进行了更新。因此，Swagger 3.0对应的就是OpenAPI //代码效果参考：http://hnjlyzjd.com/hw/wz_24649.html
3.0版本，它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比，Swagger 3.0更加强调对RESTful API的支持和规范化，提供了更丰富和灵活的定义方式，并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。3：SpringFox工具（不推荐）
Springfox是一套可以帮助Java开发者自动生成API文档的工具，它是基于Swagger 2.x基础上开发的。Swagger已经成为了RESTful API文档生态系统的事实标准，而Springfox是一个用于集成Swagger2.x到Spring应用程序中的库。而且Springfox提供了一些注解来描述API接口、参数和返回值，并根据这些信息生成Swagger UI界面，从而方便其他开发人员查看和使用您的API接口。此外，Springfox还支持自动生成API文档和代码片段，简化了开发人员的工作量。除了集成Swagger 2.x，Springfox还提供了一些额外功能，例如自定义Swagger文档、API版本控制、请求验证等等。这些功能使得Springfox可以胜任各种类型和规模的应用程序，同时还可以提高代码质量和开发效率。总之，Springfox是一个非常有用的工具，它可以帮助Java开发者快速、简单地集成Swagger2.x，并为他们的应用程序生成高质量的API文档。无论您开发的是大型企业应用程序还是小型服务，使用Springfox都能够提高团队的生产力和代码质量。
注意：但是随着时间的推移，Swagger2.x终究成为历史，所以我们可以看出springfox-boot-starter的坐标从3.0.0版本（2020年7月14日）开始就一直没有更新；也得注意的是springfox-swagger2坐标和springfox-boot-start是一样的，但springfox-boot-start只有3.0.0版本。这里我就不在使用Swagger2.x版本，具体可以在网上找到许多，因为大部分的网上资料都是Swagger2.x的方式。
4：SpringDoc工具（推荐）
SpringDoc对应坐标是springdoc-openapi-ui，它是一个集成Swagger UI和ReDoc的接口文档生成工具，在使用上与springfox-boot-starter类似，但提供了更为灵活、功能更加强大的工具。其中除了可以生成Swagger UI风格的接口文档，还提供了ReDoc的文档渲染方式，可以自动注入OpenAPI规范的JSON描述文件，支持OAuth2、JWT等认证机制，并且支持全新的OpenAPI 3.0规范。
SpringDoc是基于OpenAPI 3.0规范构建的，因此推荐在Spring Boot 2.4及以上版本中使用springdoc-openapi-ui库来集成Swagger3.x。在这些版本中，springdoc-openapi-ui库已被广泛应用，并且得到了社区的大力支持和推广。而在Spring Boot 2.3及其以下版本，可以使用springfox-boot-starter库来集成Swagger2.x。
SpringDoc是有着更加先进的技术架构和更好的扩展性，使得其逐渐取代了springfox-boot-starter工具包，成为了当前Spring Boot生态中最受欢迎的API文档工具之一。同时springdoc-openapi-ui还拥有更为完善的开发文档和社区支持，从而吸引了越来越多的开发者加入到这个项目中。因此作为一个Spring Boot开发者，如果想要快速、方便地生成符合OpenAPI 3.0规范的接口文档，建议使用springdoc-openapi-ui这个优秀的工具。
回到目录 ↑↑↑二：SpringBoot集成Open API 3.0（Swagger3.0）
具体参考Gitee： （OpenAPI_3_Demo_Swagger3项目）
如访问自己项目Swagger地址：
我们在SpringBoot中想集成Swagger3.0，一般不选择原生的Maven坐标，而是选择 springdoc-openapi-ui的Maven坐标，它可以很好的和Spring或SpringBoot项目集成；这个坐标也被Spring社区广泛支持和认可，并被认为是集成Swagger UI和OpenAPI规范的一个优秀选择。下面将直接介绍使用。
1：引入Maven依赖
[/span>dependency
[/span>groupId
[/span>artifactId
[/span>version
说明：上面的坐标内部导入了Swagger3.0的原生依赖（我们只需要在SpringBoot导入springdoc-openapi-ui即可）
①：io.swagger.core.v3:swagger-core:2.2.9
Swagger Core是Swagger 3.x规范的核心实现，提供了一组Java API，用于生成和处理OpenAPI规范文件。
它包括Swagger的核心功能，例如Model、Schema、Parameter、Response等，是构建Swagger API的必要条件。
②：io.swagger.core.v3:swagger-annotations:2.2.9
Swagger Annotations是一个用于编写Swagger API文档的Java注解库，提供了一组注解，用于描述API元数据。
例如，@Operation、@Parameter、@ApiResponse等注解基本包含了OpenAPI规范中的所有元素。
③：io.swagger.core.v3:swagger-models:2.2.9
Swagger Models是Swagger 3.x规范的Java模型库，提供了一组Java模型类，用于表示OpenAPI规范文件。
它包含了OpenAPI规范中的所有数据模型，例如PathItem、Operation、Parameter、Components等。
2：配置SwaggerOpenApiConfig（配置类方式）
注：io.swagger.v3.oas.annotations 是Swagger注解包，而io.swagger.v3.oas.models是Swagger配置类对象方式
其实我们通过配置类的方式创建一个OpenAPI的Bean对象就可以创建Swagger3.0的文档说明，下面我就直创建。
OpenAPI对象是Swagger中的核心类之一，用于描述整个API的结构和元数据。可以理解为一个API文档对象，其中包含了许多元素，如：
①：openapi属性：
表示使用的 OpenAPI 规范版本（例如 3.0.1）。
②：info属性：
表示API的基本信息，包括标题、版本号、描述、联系人等。使用Info类来创建这个对象。
③：servers属性：
表示服务器地址或者URL模板列表。每个URL模板可以包含占位符，这些占位符可以被路径参数或者查询参数替换。
使用Server类来创建这个对象。
④：paths属性（推荐使用注解方式，不推荐使用配置类配置）：
表示API的所有路径和操作信息，使用PathItem类来描述每一个路径，使用Operation类来描述操作。
⑤：components属性：
表示API的组件信息，比如响应模板、请求模板和安全方案等。
使用Schema、Response、Parameter、SecurityScheme等类来创建这些对象。
⑥：tags属性：
表示API的标签信息，用于对相似的操作进行分组。
⑦：addServersItem(Server server)方法：
向servers属性中添加一个Server对象。
⑧：addPaths(String name, PathItem pathItem)方法：
向paths属性中添加一个PathItem对象，其中name参数表示路径模板。
⑨：addTag(Tag tag)方法：
向tags属性中添加一个Tag对象。
⑩：setComponents(Components components)方法：
设置components属性的值。
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 org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;
import java.util.HashMap;
/ 这是一个普通的Swagger配置文档，其中不包含API接口的配置（API接口的配置推荐使用注解方式）
@author Anhui OuYang
@version 1.0
/
@SpringBootConfiguration
public class SwaggerOpenApiConfig {
/
构建Swagger3.0文档说明
@return 返回 OpenAPI
/
@Bean
public OpenAPI customOpenAPI() {
// 联系人信息(contact)，构建API的联系人信息，用于描述API开发者的联系信息，包括名称、URL、邮箱等
// name：文档的发布者名称 url：文档发布者的网站地址，一般为企业网站 email：文档发布者的电子邮箱
Contact contact = new Contact()
.extensions(new HashMap()); // 使用Map配置信息（如key为"name","email","url"）
// 授权许可信息(license)，用于描述API的授权许可信息，包括名称、URL等；假设当前的授权信息为Apache 2.0的开源标准
License license = new License()
.name("Apache 2.0") // 授权名称
.url("") // 授权信息
.identifier("Apache-2.0") // 标识授权许可
.extensions(new HashMap());// 使用Map配置信息（如key为"name","url","identifier"）
//创建Api帮助文档的描述信息、联系人信息(contact)、授权许可信息(license)
Info info = new Info()
.title("Swagger3.0 (Open API) 框架学习示例文档") // Api接口文档标题（必填）
.description("学习Swagger框架而用来定义测试的文档") // Api接口文档描述
.version("1.2.1") // Api接口版本
.termsOfService("") // Api接口的服务条款地址
.license(license) // 设置联系人信息
.contact(contact); // 授权许可信息
// 返回信息
return new OpenAPI()
.openapi("3.0.1") // Open API 3.0.1(默认)
.info(info); // 配置Swagger3.0描述信息
}
}
3：配置SwaggerOpenApiConfig（注解方式）
上面我们使用了Java代码创建Bean的方式，其实这种写起来感觉还行，但是在使用了注解方式是很舒服的，下面就简单说明：
定义Swagger3.0配置信息注解：@OpenAPIDefinition （具体参考 io.swagger.v3.oas.annotations）
注意：这个注解全局只能配置一个，主要配置文档信息和安全配置
说明：用于描述整个API的元信息和全局属性，可以定义和描述，包括API版本、基本信息、服务器信息、安全方案等
常用属性：
①：info：用于描述 API 基本信息的对象，包括标题、版本号、描述等属性；
②：servers：用于描述 API 服务的 URL 和配置信息的数组；
③：security：用于描述 API 安全方案的数组，其中每个安全方案包含多个安全需求；
④：tags：用于描述 API 标签的数组，每个标签包含名称、描述等属性；
⑤：externalDocs：用于描述外部文档链接的对象，包含描述和 URL 两个属性。
import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.servers.Server;
import org.springframework.boot.SpringBootConfiguration;
/
@author Anhui OuYang
@version 1.0
**/
@SpringBootConfiguration
@OpenAPIDefinition(
// ## API的基本信息，包括标题、版本号、描述、联系人等
info = @Info(
title = "Swagger3.0 (Open API) 框架学习示例文档", // Api接口文档标题（必填）
description = "学习Swagger框架而用来定义测试的文档", // Api接口文档描述
version = "1.2.1", // Api接口版本
termsOfService = "", // Api接口的服务条款地址
contact = @Contact(
),
license = @License( // 设置联系人信息
name = "Apache 2.0", // 授权名称
url = "" // 授权信息
)
),
// ## 表示服务器地址或者URL模板列表，多个服务地址随时切换（只不过是有多台IP有当前的服务API）
servers = {
@Server(url = "", description = "本地服务器一服务"),
@Server(url = "", description = "本地服务器二服务"),
},
externalDocs = @ExternalDocumentation(description = "更多内容请查看该链接", url = "xxx"))
public class SwaggerOpenApiConfig {
}
4：配置API接口信息（注解，重要）
说了这么久，Swagger3.0的全局基本信息配置是处理好了，接下来就是配置接口了，因为我之前写了Controller代码，但是没有接口配置信息，这里我就使用Swagger的方式进行一个简单的配置。
### 示例代码，不是太明白属性的可以看下面属性介绍（具体的代码需要查看git）
// 响应对象模型定义
@Data
@AllArgsConstructor
@Schema(description = "响应返回数据对象")
public class AjaxResult {
@Schema(
title = "code",
description = "响应码",
format = "int32",
requiredMode = Schema.RequiredMode.REQUIRED
)
private Integer code;
@Schema(
title = "msg",
description = "响应信息",
accessMode = Schema.AccessMode.READ_ONLY,
example = "成功或失败",
requiredMode = Schema.RequiredMode.REQUIRED
)
private String msg;
@Schema(title = "data", description = "响应数据", accessMode = Schema.AccessMode.READ_ONLY)
private Object data;
}
// 模型定义示例：
@Data
@AllArgsConstructor
@Schema(title = "学生模型VO", description = "响应视图学生模型VO")
public class<span style="color: rg
