共计 3930 个字符,预计需要花费 10 分钟才能阅读完成。
Swagger 3.0 公布曾经有一段时间了,它于 2020.7 月 公布,但目前市面上应用的支流版本还是 Swagger 2.X 版本和大量的 1.X 版本,然而作为一名合格的程序员怎么能不折腾新技术呢?所以本期就大家带来一篇最新版 Swagger 的内容,本文会带大家看最新版 Swagger 有哪些扭转?又是如何将老版本 Swagger 降级到新版的?
Swagger 是什么?
Swagger 是一个用于生成、形容和调用 RESTful 接口的 Web 服务。艰深的来讲,Swagger 就是将我的项目中所有(想要裸露的)接口展示在页面上,并且能够进行接口调用和测试的服务。
PS:Swagger 遵循了 OpenAPI 标准,OpenAPI 是 Linux 基金会的一个我的项目,试图通过定义一种用来形容 API 格局或 API 定义的语言,来标准 RESTful 服务开发过程。
Swagger 官网地址:https://swagger.io/
Swagger 有什么用?
从上述 Swagger 定义咱们不难看出 Swagger 有以下 3 个重要的作用:
- 将我的项目中所有的接口展示在页面上,这样后端程序员就不须要专门为前端使用者编写专门的接口文档;
- 当接口更新之后,只须要批改代码中的 Swagger 形容就能够实时生成新的接口文档了,从而 躲避了接口文档老旧不能应用的问题;
- 通过 Swagger 页面,咱们能够 间接进行接口调用,升高了我的项目开发阶段的调试老本。
Swagger 旧版本应用
Swagger 旧版本也就是目前市面上支流的 V2 版本是 Swagger 2.9.2,在讲新版本之前,咱们先来回顾一下 Swagger 2.9.2 是如何应用的。
Swagger 2.9.2 的应用分为以下 4 步:
- 增加依赖
- 开启 Swagger 性能
- 配置 Swagger 文档摘要信息
- 调用接口拜访
上面咱们别离来看。
1. 增加依赖
首先,咱们要去 mvnrepository 查问 Swagger 的依赖,搜寻“springfox”关键字,失去后果的前两条依赖信息,就是咱们想要的后果,如下图所示:
将这两个依赖增加带我的项目中:
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
为什么是“springfox”?
问:咱们要应用的是 Swagger,为什么要搜寻“springfox”?
答:Swagger 能够看作是一个遵循了 OpenAPI 标准的一项技术,而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 AOP 和 DI 一样,前者是思维,而后者是实现。
2. 开启 Swagger
在 Spring Boot 的启动类或配置类中增加 @EnableSwagger2
正文,开启 Swagger,局部外围代码如下:
@EnableSwagger2
@SpringBootApplication
public class Application {...
3. 配置摘要信息
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2) // 1.SWAGGER_2
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerv2.controller")) // 2. 设置扫描门路
.build();}
}
4. 拜访 Swagger
我的项目失常启动之后应用“http://localhost:8080/swagger-ui.html”拜访 Swagger 页面,如下图所示:
Swagger 最新版应用
Swagger 最新版的配置步骤和旧版本是一样,只是每个具体的配置项又略有不同,具体步骤如下。
1. 增加依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
从上述配置能够看出,Swagger 新版本的依赖项只有一个,而旧版本的依赖项有两个,相比来说也简洁了很多。
2. 开启 Swagger
在 Spring Boot 的启动类或配置类中增加 @EnableOpenApi
正文,开启 Swagger,局部外围代码如下:
@EnableOpenApi
@SpringBootApplication
public class Application {...
3. 配置摘要信息
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {return new Docket(DocumentationType.OAS_30) // v2 不同
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // 设置扫描门路
.build();}
}
从上述代码能够看出 Docket
的配置中只有文档的类型设置新老版本是不同的,新版本的配置是 OAS_30
而旧版本的配置是 SWAGGER_2
。
PS:OAS 是 OpenAPI Specification 的简称,翻译成中文就是 OpenAPI 说明书。
4. 拜访 Swagger
新版本的 Swagger 拜访地址和老版本的地址是不同的,新版版的拜访地址是“localhost:8080/swagger-ui/””,如下图所示:
新版本 VS 老版本
新版本和老版本的区别次要体现在以下 4 个方面:
- 依赖项的增加不同:新版本只须要增加一项,而老版本须要增加两项;
- 启动 Swagger 的注解不同:新版本应用的是
@EnableOpenApi
,而老版本是@EnableSwagger2
; - Docket(文档摘要信息)的文件类型配置不同:新版本配置的是
OAS_3
,而老版本是SWAGGER_2
; - Swagger UI 拜访地址不同:新版本拜访地址是“http://localhost:8080/swagger-ui/”,而老版本拜访地址是“http://localhost:8080/swagger-ui.html”。
总结
Swagger 新版本让人印象粗浅的长处有两个:第一,配置变得简略了,比方依赖项配置缩小了 50%,第二,新版 Swagger 页面设计格调有了不小的扭转,新版的页面让人感觉更加现代化也更加具备科技感了,总体来说好看了不少。
值得一提的是 Swagger 的整个降级过程很平滑,从老版本升级到新版本,只须要简略的配置即可,那些用于形容接口的注解还是连续了老版本的用法,这样就能够在不批改大部分次要代码的状况下,能够胜利到最新版本啦。
关注公号「Java 中文社群」查看本文(Swagger 3)视频版内容。