主要內(nèi)容

1.Swagger2簡介

2.?Springfox

3.?Swagger2極致用法

4.?Swagger-UI使用

5.?Swagger2配置

6.?Swagger2常用注解

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

一、Swagger簡介

1前言

接口文檔對于前后端開發(fā)人員都十分重要。尤其近幾年流行前后端分離后接口文檔又變成重中之重。接口文檔固然重要，但是由于項目周期等原因后端人員經(jīng)常出現(xiàn)無法及時更新，導(dǎo)致前端人員抱怨接口文檔和實際情況不一致。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

很多人員會抱怨別人寫的接口文檔不規(guī)范，不及時更新。但是當(dāng)自己寫的時候確實最煩去寫接口文檔。這種痛苦只有親身經(jīng)歷才會牢記于心。

如果接口文檔可以實時動態(tài)生成就不會出現(xiàn)上面問題。

Swagger可以完美的解決上面的問題。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

2Open API 是什么

Open API規(guī)范(OpenAPI Specification)以前叫做Swagger規(guī)范，是REST API的API描述格式。

Open API文件允許描述整個API，包括：

?每個訪問地址的類型。POST或GET。

?每個操作的參數(shù)。包括輸入輸出參數(shù)。

?認證方法。

?連接信息，聲明，使用團隊和其他信息。

Open API規(guī)范可以使用YAML或JSON格式進行編寫。這樣更利于我們和機器進行閱讀。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

OpenAPI規(guī)范（OAS）為REST API定義了一個與語言無關(guān)的標準接口，允許人和計算機發(fā)現(xiàn)和理解服務(wù)的功能，而無需訪問源代碼，文檔或通過網(wǎng)絡(luò)流量檢查。正確定義后，消費者可以使用最少量的實現(xiàn)邏輯來理解遠程服務(wù)并與之交互。

然后，文檔生成工具可以使用OpenAPI定義來顯示API，使用各種編程語言生成服務(wù)器和客戶端的代碼生成工具，測試工具以及許多其他用例。

源碼和說明參照：

1?Swagger簡介

Swagger是一套圍繞Open API規(guī)范構(gòu)建的開源工具，可以幫助設(shè)計，構(gòu)建，記錄和使用REST API。

Swagger工具包括的組件：

Swagger Editor ：基于瀏覽器編輯器，可以在里面編寫Open API規(guī)范。類似Markdown具有實時預(yù)覽描述文件的功能。

Swagger UI：將Open API規(guī)范呈現(xiàn)為交互式API文檔。用可視化UI展示描述文件。

Swagger Codegen：將OpenAPI規(guī)范生成為服務(wù)器存根和客戶端庫。通過Swagger Codegen可以將描述文件生成html格式和cwiki形式的接口文檔，同時也可以生成多種言語的客戶端和服務(wù)端代碼。

Swagger Inspector：和Swagger UI有點類似，但是可以返回更多信息，也會保存請求的實際參數(shù)數(shù)據(jù)。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

Swagger Hub：集成了上面所有項目的各個功能，你可以以項目和版本為單位，將你的描述文件上傳到Swagger Hub中。在Swagger Hub中可以完成上面項目的所有工作，需要注冊賬號，分免費版和收費版。

使用Swagger，就是把相關(guān)的信息存儲在它定義的描述文件里面（yml或json格式），再通過維護這個描述文件可以去更新接口文檔，以及生成各端代碼

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

?

一、?Springfox

使用Swagger時如果碰見版本更新或迭代時，只需要更改Swagger的描述文件即可。但是在頻繁的更新項目版本時很多開發(fā)人員認為即使修改描述文件（yml或json）也是一定的工作負擔(dān)，久而久之就直接修改代碼，而不去修改描述文件了，這樣基于描述文件生成接口文檔也失去了意義。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

Marty Pitt編寫了一個基于Spring的組件Swagger-springmvc。Spring-fox就是根據(jù)這個組件發(fā)展而來的全新項目。

Spring-fox是根據(jù)代碼生成接口文檔，所以正常的進行更新項目版本，修改代碼即可，而不需要跟隨修改描述文件。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

Spring-fox利用自身AOP特性，把Swagger集成進來，底層還是Swagger。但是使用起來確方便很多。

所以在實際開發(fā)中，都是直接使用spring-fox。

三、?Swagger極致用法

1?編寫SpringBoot項目

編寫SpringBoot項目，項目中controller中包含一個Handler，測試項目，保證程序可以正確運行。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw

1?導(dǎo)入Spring-fox依賴

在項目的pom.xml中導(dǎo)入Spring-fox依賴。目前最新版本為2.9.2，所以導(dǎo)入的依賴也是這個版本。其中springfox-Swagger2是核心內(nèi)容的封裝。springfox-Swagger-ui是對Swagger-ui的封裝。

想要了解、學(xué)習(xí)更多，請點擊：https://www.bilibili.com/video/BV1YK4y1S7pw