文章目录
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