SpringBoot开发——整合Swagger
文章目录
- 1. Swagger概述
- 2. Swagger发展
- 2.1 Swagger 1.x 阶段（2011-2014年）
- 2.2 Swagger 2.x 阶段（2014-2017年）
- 2.3 OpenAPI 阶段（2017年至今，也被称为Swagger 3.x）
- 3. Spring Boot整合Swagger环境搭建
- 3.1 SpringDoc OpenAPI版本介绍
- 3.2 引入Maven依赖
- 3.2 配置文件
- 3.3 控制器和注解
1. Swagger概述
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。
它使得前后端分离开发更加方便，有利于团队协作。
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文件中添加