关于java:最新版Swagger-3升级指南和新功能体验

Swagger 3.0 公布曾经有一段时间了，它于 2020.7 月公布，但目前市面上应用的支流版本还是 Swagger 2.X 版本和大量的 1.X 版本，然而作为一名合格的程序员怎么能不折腾新技术呢？所以本期就大家带来一篇最新版 Swagger 的内容，本文会带大家看最新版 Swagger 有哪些扭转？又是如何将老版本 Swagger 降级到新版的？

Swagger 是一个用于生成、形容和调用 RESTful 接口的 Web 服务。艰深的来讲，Swagger 就是将我的项目中所有（想要裸露的）接口展示在页面上，并且能够进行接口调用和测试的服务。

PS：Swagger 遵循了 OpenAPI 标准，OpenAPI 是 Linux 基金会的一个我的项目，试图通过定义一种用来形容 API 格局或 API 定义的语言，来标准 RESTful 服务开发过程。

Swagger 官网地址：https://swagger.io/

从上述 Swagger 定义咱们不难看出 Swagger 有以下 3 个重要的作用：

将我的项目中所有的接口展示在页面上，这样后端程序员就不须要专门为前端使用者编写专门的接口文档；
当接口更新之后，只须要批改代码中的 Swagger 形容就能够实时生成新的接口文档了，从而 躲避了接口文档老旧不能应用的问题；
通过 Swagger 页面，咱们能够 间接进行接口调用，升高了我的项目开发阶段的调试老本。

Swagger 旧版本也就是目前市面上支流的 V2 版本是 Swagger 2.9.2，在讲新版本之前，咱们先来回顾一下 Swagger 2.9.2 是如何应用的。

Swagger 2.9.2 的应用分为以下 4 步：

增加依赖
开启 Swagger 性能
配置 Swagger 文档摘要信息
调用接口拜访

上面咱们别离来看。

首先，咱们要去 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>

问：咱们要应用的是 Swagger，为什么要搜寻“springfox”？

答：Swagger 能够看作是一个遵循了 OpenAPI 标准的一项技术，而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 AOP 和 DI 一样，前者是思维，而后者是实现。

在 Spring Boot 的启动类或配置类中增加 @EnableSwagger2 正文，开启 Swagger，局部外围代码如下：

@EnableSwagger2
@SpringBootApplication
public class Application {...

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();}
}

我的项目失常启动之后应用“http://localhost:8080/swagger-ui.html”拜访 Swagger 页面，如下图所示：

Swagger 最新版的配置步骤和旧版本是一样，只是每个具体的配置项又略有不同，具体步骤如下。

<!-- 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 新版本的依赖项只有一个，而旧版本的依赖项有两个，相比来说也简洁了很多。

在 Spring Boot 的启动类或配置类中增加 @EnableOpenApi 正文，开启 Swagger，局部外围代码如下：

@EnableOpenApi
@SpringBootApplication
public class Application {...

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 说明书。

新版本的 Swagger 拜访地址和老版本的地址是不同的，新版版的拜访地址是“localhost:8080/swagger-ui/””，如下图所示：

新版本和老版本的区别次要体现在以下 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）视频版内容。

关于java:最新版Swagger-3升级指南和新功能体验

Swagger 是什么？

Swagger 有什么用？

Swagger 旧版本应用

1. 增加依赖

为什么是“springfox”？

2. 开启 Swagger

3. 配置摘要信息

4. 拜访 Swagger

Swagger 最新版应用

1. 增加依赖

2. 开启 Swagger

3. 配置摘要信息

4. 拜访 Swagger

新版本 VS 老版本

总结