SpringBoot开发——整合Swagger

1. Swagger概述

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。
它使得前后端分离开发更加方便，有利于团队协作。

作用

• 接口文档在线自动生成
• 功能测试

Swagger是一组开源项目，其中主要项目如下：

• Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
• Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
• Swagger-js: 用于JavaScript的Swagger实现。
• Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
• Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
• Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

2. Swagger发展

2.1 Swagger 1.x 阶段（2011-2014年）

起始与定位： Swagger 最初由 Tony Tam 在2011年创建，旨在作为一个简单的API文档生成工具。
核心功能：通过对JAX-RS 和 Jersey注解的支持，Swagger 1.x能够自动生成API文档，使得API文档的维护变得更加容易。在这个阶段，Swagger还没有完全成熟，主要支持基本的API描述和文档生成。

2.2 Swagger 2.x 阶段（2014-2017年）

重大变革：Swagger 2.x发生了重大变化，从单一的文档生成工具演变为一个完整的API开发和管理平台。

新增功能：

• 引入了强大的注解支持，可以描述API的细节信息，如请求参数、返回类型等。
• 定义了RESTful API的元数据，如API描述、标签等。
• 引入了OpenAPI规范（原名Swagger规范），为API定义提供了更严格的标准和规则。

2.3 OpenAPI 阶段（2017年至今，也被称为Swagger 3.x）

规范更名：在2017年，Swagger 2.x的规范被捐赠给Linux基金会，并正式更名为OpenAPI规范。

发展与普及：OpenAPI规范不仅继承了Swagger 2.x的特性，还提供了更加全面和严格的API定义规范，并且扩展了对非RESTful API的支持。随着OpenAPI规范的普及，越来越多的API开发者开始使用Swagger/OpenAPI来开发、测试和文档化他们的RESTful API。

工具与服务：OpenAPI规范采用JSON或YAML格式编写，并支持多种数据类型。基于OpenAPI规范，开发了许多工具和服务，如Swagger UI、Swagger Codegen、SwaggerHub等，进一步扩展了Swagger的功能，使其成为了一个更加完整、强大和易于使用的API定义和管理平台。

3. Spring Boot整合Swagger环境搭建

3.1 SpringDoc OpenAPI版本介绍

Springdoc OpenAPI 1.x

JDK支持：支持JDK 8及以上版本。
Spring Boot支持：适用于Spring Boot 2.x及更早版本。

Springdoc OpenAPI 2.x

JDK支持：最新版本要求JDK 11及以上。
Spring Boot支持：专为Spring Boot 3.x设计。

3.2 引入Maven依赖

在Spring Boot项目中，可以通过在pom.xml文件中添加Swagger相关的依赖来启用Swagger。

这里以Swagger 3为例，Spring Boot 2.6.x或更高版本推荐使用springfox-boot-starter。

<dependency>
    <groupId