最新版Swagger 3升級指南和新功能體驗！
阿新 • • 發佈：2021-03-15
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/](https://swagger.io/)
## Swagger 有什麼用？
從上述 Swagger 定義我們不難看出 Swagger 有以下 3 個重要的作用：
1. **將專案中所有的介面展現在頁面上**，這樣後端程式設計師就不需要專門為前端使用者編寫專門的介面文件；
1. 當介面更新之後，只需要修改程式碼中的 Swagger 描述就可以實時生成新的介面文件了，從而**規避了介面文件老舊不能使用的問題**；
1. 通過 Swagger 頁面，我們可以**直接進行介面呼叫，降低了專案開發階段的除錯成本**。
## Swagger 舊版本使用
Swagger 舊版本也就是目前市面上主流的 V2 版本是 Swagger 2.9.2，在講新版本之前，我們先來回顧一下 Swagger 2.9.2 是如何使用的。
Swagger 2.9.2 的使用分為以下 4 步：
1. 新增依賴
1. 開啟 Swagger 功能
1. 配置 Swagger 文件摘要資訊
1. 呼叫介面訪問
下面我們分別來看。
#### 1.新增依賴
首先，我們要去 mvnrepository 查詢 Swagger 的依賴，搜尋“springfox”關鍵字，得到結果的前兩條依賴資訊，就是我們想要的結果，如下圖所示：
將這兩個依賴新增帶專案中：
```java
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
```
#### 為什麼是“springfox”？
問：我們要使用的是 Swagger，為什麼要搜尋“springfox”？
答：**Swagger 可以看作是一個遵循了 OpenAPI 規範的一項技術，而 springfox 則是這項技術的具體實現。** 就好比 Spring 中的 AOP 和 DI 一樣，前者是思想，而後者是實現。
#### 2.開啟Swagger
在 Spring Boot 的啟動類或配置類中新增 `@EnableSwagger2` 註釋，開啟 Swagger，部分核心程式碼如下：
```java
@EnableSwagger2
@SpringBootApplication
public class Application {...
```
#### 3.配置摘要資訊
```java
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.新增依賴
```xml
io.springfox
springfox-boot-starter
3.0.0
```
從上述配置可以看出，Swagger 新版本的依賴項只有一個，而舊版本的依賴項有兩個，相比來說也簡潔了很多。
#### 2.開啟Swagger
在 Spring Boot 的啟動類或配置類中新增 `@EnableOpenApi` 註釋，開啟 Swagger，部分核心程式碼如下：
```java
@EnableOpenApi
@SpringBootApplication
public class Application {...
```
#### 3.配置摘要資訊
```java
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`。
>