網上收集整理，個人學習記錄。

-------------------------------------------------------------------------------------------------------------------

本文說明：

1.版本：springfox-swagger2（2.4.0）springfox-swagger-ui （2.4.0） 
2.需要對swagger完成整合，如果沒有整合的可以參考我的另一篇文章：Spring boot整合swagger2

常用註解介紹：

- @Api()用於類
表示標識這個類是swagger的資源 
- @ApiOperation()用於方法
表示一個http請求的操作 
- @ApiParam()用於方法，引數，欄位說明
表示對引數的新增元資料（說明或是否必填等） 
- @ApiModel()用於類 
表示對類進行說明，用於引數用實體類接收 
- @ApiModelProperty()用於方法，欄位 
表示對model屬性的說明或者資料操作更改 
- @ApiIgnore()用於類，方法，方法引數 
表示這個方法或者類被忽略 
- @ApiImplicitParam() 用於方法 
表示單獨的請求引數 
- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam
- @ApiResponses
用在請求的方法上，表示一組響應
- @ApiResponse
用在@ApiResponses中，一般用於表達一個錯誤的響應資訊

常用註解使用示例：

@Api() 
用於類；表示標識這個類是swagger的資源 
tags–表示說明 
value–也是說明，可以使用tags替代 
但是tags如果有多個值，會生成多個list

例：

@Api(value="swaggerController",tags={"swaggerDemoController相關的api1","swaggerDemoController相關的api2"})
public class SwaggerDemoController {

}

@ApiOperation() 用於方法；表示一個http請求的操作 
value用於方法描述 
notes用於提示內容 
tags可以重新分組（視情況而用）

例：

@ApiOperation(value = "根據id查詢學生資訊", notes = "查詢資料庫中某個的學生資訊")

@ApiOperation(value = "根據id查詢學生資訊", notes = "查詢資料庫中某個的學生資訊",tags={"swaggerDemoController的getStudent1",
        "swaggerDemoController的getStudent2"})

@ApiParam() 用於方法，引數，欄位說明；表示對引數的新增元資料（說明或是否必填等） 
name–引數名 
value–引數說明 
required–是否必填

例:

public Student getStudent(@PathVariable @ApiParam(name="id",value="學生id說明",required=true) int id) {
    logger.info("開始查詢某個學生資訊");
    return studentService.selectStudentById(id);
}

@ApiModel()用於類 ；表示對類進行說明，用於引數用實體類接收 
value–表示物件名 
description–描述 
都可省略 

@ApiModelProperty()用於方法，欄位； 表示對model屬性的說明或者資料操作更改 
value–欄位說明 
name–重寫屬性名字 
dataType–重寫屬性型別 
required–是否必填 
example–舉例說明 
hidden–隱藏

例:

@ApiModel(value = "user物件", description = "使用者物件user")
public class User implements Serializable {
    private static final long serialVersionUID = 1L;
    private String userId;
    @ApiModelProperty(value = "使用者名稱", name = "userName", example = "baidu1")
    private String userName;
    @ApiModelProperty(value = "狀態", name = "state", required = true)
    private String state;
    @ApiModelProperty(hidden = true)
    private String extendColumn1;

}

@ApiIgnore()用於類或者方法上，可以不被swagger顯示在頁面上 

例：

@ApiIgnore()
public User getUser(@RequestBody @ApiParam(name = "使用者物件", value = "傳入json格式", required = false) User user) {
    logger.info("開始查詢某個使用者資訊");
    user.setUserId("abc");
    return user;
}

如下圖 getUser() 已經沒有被顯示了

@ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

@ApiImplicitParam() 用於方法，表示單獨的請求引數 
name–引數ming 
value–引數說明 
dataType–資料型別 
paramType–引數型別 
example–舉例說明
例:

@ApiImplicitParams({
        @ApiImplicitParam(name = "name", value = "學生名", dataType = "String", paramType = "query", example =
                "baidu2"),
        @ApiImplicitParam(name = "id", value = "學生id", dataType = "String", paramType = "path")})
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
public Student getStudent(@PathVariable @ApiParam(name = "id", value = "學生id說明", required = true) String id) {
    logger.info("開始查詢某個學生資訊");
    return studentService.selectStudentById(id);
}

@ApiResponses：用於請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
code：數字，例如400
message：資訊，例如"請求引數沒填好"

例:

@ApiResponses({
        @ApiResponse(code = 400, message = "請求引數沒填好"),
        @ApiResponse(code = 404, message = "請求路徑沒有或頁面跳轉路徑不對")
})

注意：code值必須是http 返回code值，如果不是會報錯

例：

@ApiResponses({
        @ApiResponse(code = 12345, message = "上山打老虎"),
        @ApiResponse(code = 400, message = "請求引數沒填好"),
        @ApiResponse(code = 404, message = "請求路徑沒有或頁面跳轉路徑不對")
})

參考資料：