接口文檔神器Swagger（上篇）

本文來自網易雲社區

做者：李哲

接口文檔管理一直是一個讓人頭疼的問題，伴隨着各類接口文檔管理平臺涌現，如阿里開源的rap，ShowDoc，sosoapi，等等（網上能找到不少這種管理平臺，包括咱們本身作的idoc）。這些平臺都是一個共同特色，建立文檔，編輯，保存文檔，一些功能強大的還有mock，統計接口信息等功能，因此這些平臺更像一個接口文檔的存儲管理系統，能夠方便人們查看、編輯文檔。然而接口通常都是常常變化（添加、刪除參數），這就須要接口編寫者及時更新文檔，不然文檔將失去意義，可是頻繁去更新文檔也會花費開發很多時間。Swagger的出如今某種程度上解決了這些問題，Swagger提供了一套完整的接口文檔解決方案，其功能很是強大，下面將從Swagger簡單介紹和使用、Swagger-springmvc原理解析、Swagger其餘功能等方面介紹。

1、Swagger介紹和使用

一、 什麼是swagger

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化RESTful風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。Swagger讓部署管理和使用功能強大的API變得很是簡單。官方網站：http://swagger.io/。

Swagger採用OpenAPI規範，OpenAPI規範這類API定義語言可以幫助你更簡單、快速的表述API，尤爲是在API的設計階段做用特別突出。一旦編寫完成，API文檔能夠做爲：

·  需求和系統特性描述的根據

·  先後臺查詢、討論、自測的基礎

·  部分或者所有代碼自動生成的根據

·  其餘重要的做用，好比開放平臺開發者的手冊

二、 如何編寫API文檔

（1）定義YAML文件，而後能夠生成各類語言的代碼框架，對於後臺程序員來講，較少人會願意寫出一堆YAML格式。

（2）定義JSON格式文件，按照swagger文檔書寫規範編寫文檔，和YAML同樣只是兩種不一樣格式。

（3）經過swagger的各類語言的插件，能夠經過配置及少許代碼，生成接口文檔及測試界面。經過yaml或json書寫的是靜態文檔，須要書寫文檔中須要的內容，詳細寫法可參考：https://www.gitbook.com/book/huangwenchao/swagger/details，完成後能夠經過可視化頁面顯示接口文檔。但要完成整個項目的接口文檔書寫也很是耗時，若是是後臺開發，能夠經過簡單配置實現文檔的自動生成。

三、 Springmvc項目中使用swagger

1） 添加maven依賴

   

<dependency>

         <groupId>com.mangofactory</groupId>

         <artifactId>swagger-springmvc</artifactId>

         <version>1.0.2</version>

      </dependency>

2） 定義一個swagger配置類，添加以下註解，具體內容可參考網上demo

3） 在spring配置文件中將寫的config類添加一個bean

4） 在controller中接口處添加swagger註解和相應參數

5） Swagger UI配置

從https://github.com/swagger-api/swagger-ui 獲取3.0版本如下，2.0版本以上。其全部的dist目錄下東西放到須要集成的項目裏，本文放入src/main/webapp/WEB -INF/docs/ 目錄下。

  修改swagger/index.html文件，默認是從鏈接http://petstore.swagger.io/v2/ swagger.json獲取 API 的 JSON，這裏須要將url內容修改成http://{ip}:{port}/{project Name}/api-docs的形式，{}中的內容根據具體狀況填寫。好比本文的url值爲：http://localhost/quality /docs/api-docs。全部工做完成後，在瀏覽器中輸入上述url地址可獲得以下頁面（注：該頁面是swagger官網示例）。

接口詳情以下圖所示：

能夠根據請求參數訪問接口，若是網絡通暢將返回接口的response結果，在該頁面能夠看到接口的基本詳情，並且若是後臺接口發生變化，該頁面中的信息也會隨着變化，這樣接口的內容就是實時變化的，相對於靜態的文檔每次改動都須要開發更新文檔的方式，該方式無疑是很是好的解決方案。

若是過程當中發現沒有達到預期的結果，請檢查swagger ui位置是否正確；spring中是否添加了SwaggerConfig的bean。

四、 Springboot項目中使用swagger2

相對於springmvc中添加swagger，springboot中更加簡單。Springboot中許多配置是默認的，不用太多配置就能完成swagger的接入。具體流程以下：

1） 添加maven依賴

  

<!-- swagger框架 -->

      <dependency>

         <groupId>io.springfox</groupId>

         <artifactId>springfox-swagger2</artifactId>

         <version>2.2.2</version>

      </dependency>

      <dependency>

         <groupId>io.springfox</groupId>

         <artifactId>springfox-swagger-ui</artifactId>

         <version>2.2.2</version>

      </dependency>

2）  建立swagger2配置類，該類和springmvc中的不太同樣，具體可參考swagger官網。配置中經過@Configuration註解，讓Spring來加載該類配置。再經過@EnableSwagger2註解來啓用Swagger2。

3）  和springmvc同樣，在controller接口中編寫swagger相關的註解來標識接口信息。以下所示，經過@ApiOperation註解來給API增長說明、經過@ApiImplicitParams、@ApiImplicitParam註解來給參數增長說明。

4）  完成上述代碼添加上，啓動Spring Boot程序，訪問：http://localhost:8080/swagger- ui.html。就能看到前文所展現的RESTful API的頁面。咱們能夠再打開具體的API請求，以POST類型的/users請求爲例，可找到上述代碼中咱們配置的Notes信息以及參數user的描述信息，以下圖所示。

經過簡單的配置改動，spring就能結合swagger，經過簡單的方式自動生成接口文檔，並且以可視化頁面的形式展示，很是靈活方便。

       下面對swagger在spring中使用的一些經常使用註解進行說明：

• Api、ApiIgnore

• ApiModel

• ApiModelProperty

• ApiOperation

• ApiParam、ApiImplicitParam、ApiImplicitParams

• ApiResponse

• ApiResponses

• ResponseHeader

1）  Api註解用於類上，說明該類的做用。能夠標記一個Controller類作爲swagger 文檔資源。與Controller註解並列使用。

            @Api(value = "/user", description = "Operations about user")

屬性以下：

2） ApiOperation註解，用在方法上，說明方法的做用，與Controller中的方法並列使用。

3） ApiParam註解用在@ApiImplicitParams的方法裏邊，屬性配置：

4） ApiResponse註解用於響應配置，與Controller中的方法並列使用。屬性配置：

5） ApiResponses註解中包含ApiResponse，用於描述一組ApiResponse值。

6） ResponseHeader註解用於設置響應頭，與Controller中的方法並列使用。 屬性配置：

7） ApiImplicitParams註解用於方法上包含一組參數說明。

8） ApiImplicitParam註解用於描述請求參數，根據不一樣的paramType類型，請求的參數來源不一樣。屬性及取值以下：

9）  ApiModel註解用於表示對類進行說明，描述一個Model的信息，表示參數用實體類接收。

10）ApiModelProperty註解用於方法、字段，表示對model屬性的說明或者數據操做更改，配合ApiModel一塊兒使用。

11）ApiIgnore註解用於類或方法上，表示不須要swagger處理。

Swagger提供的註解還有其餘一些，此處不作解釋（並且高版本中的註解可能不太同樣），能夠經過官方文檔或源碼查閱，基本經常使用的註解就是這些，詳細的使用方法能夠網上查看。若是熟悉了這些註解就能夠很快的表示後臺代碼接口的信息，而後經過頁面的形式展現出來。可是swagger是如何結合spring經過簡單的配置、添加註解的方式就將接口的信息展示出來。下面將看看swagger爲何這麼神奇。

 

相關閱讀：接口文檔神器Swagger（下篇）

網易雲大禮包：https://www.163yun.com/gift

本文來自網易雲社區，經做者李哲受權發佈

相關文章：
【推薦】 大數據技術在金融行業的應用前景