[[387507]]

來源 | Java中文社群（ID：javacn666）轉(zhuǎn)載請聯(lián)系授權(quán)（微信ID：GG_Stone）

Swagger 3.0 發(fā)布已經(jīng)有一段時(shí)間了，它于 2020.7 月 發(fā)布，但目前市面上使用的主流版本還是 Swagger 2.X 版本和少量的 1.X 版本，然而作為一名合格的程序員怎么能不折騰新技術(shù)呢?所以本期就大家?guī)硪黄钚掳?Swagger 的內(nèi)容，本文會帶大家看最新版 Swagger 有哪些改變?又是如何將老版本 Swagger 升級到新版的?

Swagger 是什么?

Swagger 是一個(gè)用于生成、描述和調(diào)用 RESTful 接口的 Web 服務(wù)。通俗的來講，Swagger 就是將項(xiàng)目中所有(想要暴露的)接口展現(xiàn)在頁面上，并且可以進(jìn)行接口調(diào)用和測試的服務(wù)。

• PS：Swagger 遵循了 OpenAPI 規(guī)范，OpenAPI 是 Linux 基金會的一個(gè)項(xiàng)目，試圖通過定義一種用來描述 API 格式或 API 定義的語言，來規(guī)范 RESTful 服務(wù)開發(fā)過程。

Swagger 官網(wǎng)地址：https://swagger.io/

Swagger 有什么用?

從上述 Swagger 定義我們不難看出 Swagger 有以下 3 個(gè)重要的作用：

將項(xiàng)目中所有的接口展現(xiàn)在頁面上，這樣后端程序員就不需要專門為前端使用者編寫專門的接口文檔;

當(dāng)接口更新之后，只需要修改代碼中的 Swagger 描述就可以實(shí)時(shí)生成新的接口文檔了，從而規(guī)避了接口文檔老舊不能使用的問題;

通過 Swagger 頁面，我們可以直接進(jìn)行接口調(diào)用，降低了項(xiàng)目開發(fā)階段的調(diào)試成本。

Swagger 舊版本使用

Swagger 舊版本也就是目前市面上主流的 V2 版本是 Swagger 2.9.2，在講新版本之前，我們先來回顧一下 Swagger 2.9.2 是如何使用的。

Swagger 2.9.2 的使用分為以下 4 步：

1. 添加依賴
2. 開啟 Swagger 功能
3. 配置 Swagger 文檔摘要信息
4. 調(diào)用接口訪問

下面我們分別來看。

1.添加依賴

首先，我們要去 mvnrepository 查詢 Swagger 的依賴，搜索“springfox”關(guān)鍵字，得到結(jié)果的前兩條依賴信息，就是我們想要的結(jié)果，如下圖所示：

將這兩個(gè)依賴添加帶項(xiàng)目中：

<!-- 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 可以看作是一個(gè)遵循了 OpenAPI 規(guī)范的一項(xiàng)技術(shù)，而 springfox 則是這項(xiàng)技術(shù)的具體實(shí)現(xiàn)。就好比 Spring 中的 AOP 和 DI 一樣，前者是思想，而后者是實(shí)現(xiàn)。

2.開啟Swagger

在 Spring Boot 的啟動(dòng)類或配置類中添加 @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.設(shè)置掃描路徑 
                .build(); 
    } 
} 

4.訪問Swagger

項(xiàng)目正常啟動(dòng)之后使用“http://localhost:8080/swagger-ui.html”訪問Swagger頁面，如下圖所示：

Swagger 最新版使用

Swagger 最新版的配置步驟和舊版本是一樣，只是每個(gè)具體的配置項(xiàng)又略有不同，具體步驟如下。

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 新版本的依賴項(xiàng)只有一個(gè)，而舊版本的依賴項(xiàng)有兩個(gè)，相比來說也簡潔了很多。

2.開啟Swagger

在 Spring Boot 的啟動(dòng)類或配置類中添加 @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")) // 設(shè)置掃描路徑 
                .build(); 
    } 
} 

從上述代碼可以看出 Docket 的配置中只有文檔的類型設(shè)置新老版本是不同的，新版本的配置是 OAS_30 而舊版本的配置是 SWAGGER_2。

• PS：OAS 是 OpenAPI Specification 的簡稱，翻譯成中文就是 OpenAPI 說明書。

4.訪問Swagger

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

新版本 VS 老版本

新版本和老版本的區(qū)別主要體現(xiàn)在以下 4 個(gè)方面：

1. 依賴項(xiàng)的添加不同：新版本只需要添加一項(xiàng)，而老版本需要添加兩項(xiàng)；
2. 啟動(dòng) Swagger 的注解不同：新版本使用的是 @EnableOpenApi，而老版本是 @EnableSwagger2；
3. Docket（文檔摘要信息）的文件類型配置不同：新版本配置的是 OAS_3，而老版本是 SWAGGER_2；
4. Swagger UI 訪問地址不同：新版本訪問地址是“http://localhost:8080/swagger-ui/”，而老版本訪問地址是“http://localhost:8080/swagger-ui.html”。

 總結(jié)

Swagger 新版本讓人印象深刻的優(yōu)點(diǎn)有兩個(gè)：第一，配置變得簡單了，比如依賴項(xiàng)配置減少了 50%，第二，新版 Swagger 頁面設(shè)計(jì)風(fēng)格有了不小的改變，新版的頁面讓人感覺更加現(xiàn)代化也更加具有科技感了，總體來說美觀了不少。

值得一提的是 Swagger 的整個(gè)升級過程很平滑，從老版本升級到新版本，只需要簡單的配置即可，那些用于描述接口的注解還是延續(xù)了老版本的用法，這樣就可以在不修改大部分主要代碼的情況下，可以成功到最新版本啦。