Swagger 是一個用於生成、描述和呼叫 RESTful 介面的 Web 服務
0.前言
其實大家也知道,平時的開發中交流成本佔據了我們很大一部分時間,但前後端如果有一個好的協作方式的話能解決很多時間。這裡推薦一個文件生成器swagger。swagger是一個REST APIs文件生成工具,可以在許多不同的平臺上從程式碼註釋中自動生成,開源,支援大部分語言,社群好,總之就是一個強大,如下圖的api 文件(swagger自動生成,ui忽略)
api 地址,需要傳是沒引數,需要的傳參型別,返回的資料格式什麼都一清二楚了。
1.Swagger 是什麼?
Swagger 是一個用於生成、描述和呼叫 RESTful 介面的 Web 服務。通俗的來講,Swagger 就是將專案中所有(想要暴露的)介面展現在頁面上,並且可以進行介面呼叫和測試的服務。
PS:Swagger 遵循了 OpenAPI 規範,OpenAPI 是 Linux 基金會的一個專案,試圖通過定義一種用來描述 API 格式或 API 定義的語言,來規範 RESTful 服務開發過程。
Swagger 官網地址:https://swagger.io/
2.Swagger 有什麼用?
從上述 Swagger 定義我們不難看出 Swagger 有以下 3 個重要的作用:
- 將專案中所有的介面展現在頁面上,這樣後端程式設計師就不需要專門為前端使用者編寫專門的介面文件;
- 當介面更新之後,只需要修改程式碼中的 Swagger 描述就可以實時生成新的介面文件了,從而規避了介面文件老舊不能使用的問題
- 通過 Swagger 頁面,我們可以直接進行介面呼叫,降低了專案開發階段的除錯成本。
3.Swagger 版本說明
Swagger 3.0 釋出已經有一段時間了,它於 2020.7 月 釋出,但目前市面上使用的主流版本還是 Swagger 2.X 版本和少量的 1.X 版本,然而作為一名合格的程式設計師怎麼能不折騰新技術呢?所以本期就大家帶來一篇最新版 Swagger 的內容,本文會帶大家看最新版 Swagger 有哪些改變?又是如何將老版本 Swagger 升級到新版的?
3.1.Swagger 舊版本使用
Swagger 舊版本也就是目前市面上主流的 V2 版本是 Swagger 2.9.2,在講新版本之前,我們先來回顧一下 Swagger 2.9.2 是如何使用的。
Swagger 2.9.2 的使用分為以下 4 步:
- 新增依賴
- 開啟 Swagger 功能
- 配置 Swagger 文件摘要資訊
- 呼叫介面訪問
下面我們分別來看。
3.1.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 一樣,前者是思想,而後者是實現。
3.1.2.開啟Swagger
在 Spring Boot 的啟動類或配置類中新增 @EnableSwagger2
註釋,開啟 Swagger,部分核心程式碼如下:
@EnableSwagger2 @SpringBootApplication public class Application {...
3.1.3.配置摘要資訊
作者:王磊 連結:https://www.zhihu.com/question/63803795/answer/1780508067 來源:知乎 著作權歸作者所有。商業轉載請聯絡作者獲得授權,非商業轉載請註明出處。 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(); } }
3.1.4.訪問Swagger
專案正常啟動之後使用“http://localhost:8080/swagger-ui.html”訪問Swagger頁面,如下圖所示:
3.2.Swagger 最新版使用
Swagger 最新版的配置步驟和舊版本是一樣,只是每個具體的配置項又略有不同,具體步驟如下。
3.2.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 新版本的依賴項只有一個,而舊版本的依賴項有兩個,相比來說也簡潔了很多。
3.2.2.開啟Swagger
在 Spring Boot 的啟動類或配置類中新增 @EnableOpenApi
註釋,開啟 Swagger,部分核心程式碼如下:
@EnableOpenApi @SpringBootApplication public class Application {...
3.2.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 說明書。
3.2.4.訪問Swagger
新版本的 Swagger 訪問地址和老版本的地址是不同的,新版版的訪問地址是“localhost:8080/swagger-ui/””,如下圖所示:
3.3.新版本 VS 老版本
新版本和老版本的區別主要體現在以下 4 個方面:
- 依賴項的新增不同:新版本只需要新增一項,而老版本需要新增兩項;
- 啟動 Swagger 的註解不同:新版本使用的是
@EnableOpenApi
,而老版本是@EnableSwagger2
; - Docket(文件摘要資訊)的檔案型別配置不同:新版本配置的是
OAS_3
,而老版本是SWAGGER_2
; - Swagger UI 訪問地址不同:新版本訪問地址是“http://localhost:8080/swagger-ui/”,而老版本訪問地址是“http://localhost:8080/swagger-ui.html”。
4.總結
Swagger 新版本讓人印象深刻的優點有兩個:第一,配置變得簡單了,比如依賴項配置減少了 50%,第二,新版 Swagger 頁面設計風格有了不小的改變,新版的頁面讓人感覺更加現代化也更加具有科技感了,總體來說美觀了不少。
值得一提的是 Swagger 的整個升級過程很平滑,從老版本升級到新版本,只需要簡單的配置即可,那些用於描述介面的註解還是延續了老版本的用法,這樣就可以在不修改大部分主要程式碼的情況下,可以成功到最新版本啦。
參考---https://www.zhihu.com/question/63803795/answer/1780508067