開發十年，就只剩下這套架構體系了！ >>>   

簡介：

swagger2可以將專案的所有介面在一個UI介面上展示出來，同時表明了這個介面的用途，介面需要的引數是什麼型別引數是否必須，輸入了引數可以直接測試介面類似postman的功能，會顯示介面請求的狀態碼和返回的資料結構。

優點：

1. 大大減少前後端的溝通
2. 方便查詢和測試介面
3. 提高團隊的開發效率
4. 方便新人瞭解專案

常用註解：

swagger2是通過掃描很多的註解來獲取資料幫我們展示在ui介面上的，下面就介紹下常用的註解。

1、@Api()：用在請求的類上，表示對類的說明，也代表了這個類是swagger2的資源

引數：

tags：說明該類的作用，引數是個陣列，可以填多個。
value="該引數沒什麼意義，在UI介面上不顯示，所以不用配置"
description = "使用者基本資訊操作"

2、@ApiOperation()：用於方法，表示一個http請求訪問該方法的操作

引數：

value="方法的用途和作用"    
notes="方法的注意事項和備註"    
tags：說明該方法的作用，引數是個陣列，可以填多個。
格式：tags={"作用1","作用2"} 
（在這裡建議不使用這個引數，會使介面看上去有點亂，前兩個常用）
 

3、@ApiModel()：用於響應實體類上，用於說明實體作用

引數：

description="描述實體的作用"  

4、@ApiModelProperty：用在屬性上，描述實體類的屬性

引數：

value="使用者名稱"  描述引數的意義
name="name"    引數的變數名
required=true     引數是否必選

5、@ApiImplicitParams：用在請求的方法上，包含多@ApiImplicitParam

6、@ApiImplicitParam：用於方法，表示單獨的請求引數

引數：

name="引數ming" 
value="引數說明" 
dataType="資料型別" 
paramType="query" 表示引數放在哪裡
    · header 請求引數的獲取：@RequestHeader
    · query   請求引數的獲取：@RequestParam
    · path（用於restful介面） 請求引數的獲取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue="引數的預設值"
required="true" 表示引數是否必須傳
 

7、@ApiParam()：用於方法，引數，欄位說明 表示對引數的要求和說明

引數：

name="引數名稱"
value="引數的簡要說明"
defaultValue="引數預設值"
required="true" 表示屬性是否必填，預設為false

8、@ApiResponses：用於請求的方法上，根據響應碼錶示不同響應

一個@ApiResponses包含多個@ApiResponse

9、@ApiResponse：用在請求的方法上，表示不同的響應

引數：

code="404"    表示響應碼(int型)，可自定義
message="狀態碼對應的響應資訊"   

10、@ApiIgnore()：用於類或者方法上，不被顯示在頁面上

11、@Profile({"dev", "test"})：用於配置類上，表示只對開發和測試環境有用

 

相關推薦