SpringBoot中優雅的使用Swagger2【史上最全註解篇】-【2/2】

上篇文章講到 SpringBoot中優雅的使用Swagger2-【1/2】，還不會使用Swagger的小夥伴能夠先去看上期文章。

API使用說明

做用範圍	API	API經常使用參數	做用位置
協議集描述	@Api	@Api(tags = {"tag1","tag2","..."})	controller類
協議描述	@ApiOperation	@ApiOperation(value = "功能描述",notes = "備註")	controller類的方法
描述返回對象的意義	@ApiModel	@ApiModel(value="類名",description="類描述")	返回對象類
對象屬性	@ApiModelProperty	@ApiModelProperty(value = "類屬性描述",required = true,example = "屬性舉例",notes = "備註")	出入參數對象的字段
非對象參數集	@ApiImplicitParams	@ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam(),...})	controller的方法
非對象參數描述	@ApiImplicitParam	@ApiImplicitParam(name = "參數名",value = "參數描述",required = true,paramType = "接口傳參類型",dataType = "參數數據類型")	@ApiImplicitParams的方法裏用
Response集	@ApiResponses	@ApiResponses({ @ApiResponse(),@ApiResponse(),..})	controller的方法
Response	@ApiResponse	@ApiResponse(code = 10001, message = "返回信息")	@ApiResponses裏用
忽略註解	@ApiIgnore	@ApiIgnore	類，方法，方法參數

API使用詳細說明

@Api

做用：用來指定接口的描述文字

修飾範圍：做用在類上

@Api(tags = "TestController測試")
@RestController
public class TestController {
    ....
}

@ApiOperation

做用：用來對接口中具體方法作描述

修飾範圍：做用在方法上

@ApiOperation(value = "接口整體描述",notes = "<span style='color:red;'>詳細描述：</span>&nbsp;方法詳細描述信息")
@GetMapping("/")
public String login(String... index) {
    return "Hello login ~";
}

value：用來對接口的整體描述

notes：用來對接口的詳細描述

@ApiImplicitParams

做用：用來對接口中參數進行說明

修飾範圍：做用在方法上

參數：@ApiImplicitParam數組

@ApiImplicitParam

做用：修飾接口方法裏面的參

修飾範圍：做用方法上

參數：

• name：方法參數名稱
• value：方法參數的描述
• dataType：方法參數數據類型
• defaultValue ：方法參數默認值（給測試人員作測試用的）
• paramType ：

• • 默認query：對應方式一

    • path：對應方式二
  • body：對應方式三

方式一：url？id=1&user='qlh'後面參數

@ApiOperation(value = "接口整體描述", notes = "<span style='color:red;'>詳細描述：</span>&nbsp;方法詳細描述信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用戶名", dataType = "String", defaultValue = "qlh"),
        @ApiImplicitParam(name = "password", value = "密碼", dataType = "String", defaultValue = "123")
})
@PostMapping("/")
public String login(String username, String password) {
    return "Hello login ~";
}

方式二：url/1/2路徑後 傳參 在路徑中獲取參數

@ApiOperation(value = "接口整體描述", notes = "<span style='color:red;'>詳細描述：</span>&nbsp;方法詳細描述信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "id", dataType = "String", defaultValue = "qlh",paramType = "path"),
        @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", defaultValue = "123",paramType = "path")
})
@PostMapping("/index/{id}/{name}")
public String index(@PathVariable("id") String id, @PathVariable("name") String name) {
    return "Hello World ~";
}

方式三：在body中傳參

@ApiOperation(value = "接口整體描述", notes = "<span style='color:red;'>詳細描述：</span>&nbsp;方法詳細描述信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "id", dataType = "String", defaultValue = "xxx", paramType = "body"),
        @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", defaultValue = "123", paramType = "body")
})
@PostMapping("/index")
public String index(@RequestBody Map<String, Object> map) {
    return "Hello World ~";
}

@ApiResponses

做用：用於接口的響應結果

修改範圍：做用在接口方法上

參數：@ApiResponse數組

@ApiResponses({
        @ApiResponse(),
        @ApiResponse(),
        ...
})

@ApiResponse

做用：在ApiResponses裏面對響應碼以及響應內容進行設置

修飾範圍：做用接口方法上

參數：

• code：響應狀態碼
• message：響應狀態碼對應的響應內容

@ApiResponse(code = 10001, message = "簽名錯誤"),
@ApiResponse(code = 10002, message = "sql錯誤"),
@ApiResponse(code = 10003, message = "服務怠機,請稍後重試"),

@ApiIgnore

做用：忽略類，方法，參數。（忽略的意思：在swagger-ui.html中不顯示）

修改範圍：做用在類，方法，參數上

@ApiIgnore

實體類中swagger註解

@ApiModel

做用：用來對實體類進行說明

修飾範圍：做用在類上

@ApiModel(value="類名",description = "實體類描述")

@ApiModelProperty

做用：用來對實體類中的屬性進行說明

修飾範圍：做用在類中的屬性上

@ApiModelProperty(value = "類屬性描述",required = true,example = "屬性舉例",notes = "備註")

結束語

 至此 springboot集成swagger2就講完了，我相信，看完我這兩篇文章以後的朋友，大家就能很熟練的在java代碼中使用swagger了。

 由於目前 先後端分離比較流行，因此寫一個好的 swagger接口文檔是頗有必要的，這樣就會減小先後端由於一些接口表述不清楚，致使的後端開發人員來回和前端人員交流溝通，大大的提升了開發的效率。

 使用 swagger註解後，大家寫的接口是否是被好多同事誇獎了呢？哈哈哈。

感謝閱讀小生文章。祝你們早日富可敵國，實現財富自由。

記得點贊、評論、收藏哦。

有任何問題能夠在微信搜索公衆號：Madison龍少進行諮詢

或者微信掃描下面二維碼進行諮詢