這裡只講述@Api、@ApiOperation、@ApiImplicitParams、@ApiImplicitParam、@ApiParam、@ApiModel、@ApiModelProperty、ApiResponses、@ApiResponse這幾個常用的。
@Api：用在請求的類上，表示對類的說明
常用引數：
tags="說明該類的作用，非空時將覆蓋value的值"
value="描述類的作用"
其他引數：
description 對api資源的描述，在1.5版本後不再支援
basePath 基本路徑可以不配置，在1.5版本後不再支援
position 如果配置多個Api 想改變顯示的順序位置，在1.5版本後不再支援
produces 設定MIME型別列表（output），例："application/json, application/xml"，預設為空
consumes 設定MIME型別列表（input），例："application/json, application/xml"，預設為空
protocols 設定特定協議，例：http， https， ws， wss。
authorizations 獲取授權列表（安全宣告），如果未設定，則返回一個空的授權值。
hidden 預設為false， 配置為true 將在文件中隱藏
示例：
@Api(tags="登入請求")
@Controller
@RequestMapping(value="/highPregnant")
public class LoginController {}
@ApiOperation：用在請求的方法上，說明方法的用途、作用
常用引數：
value="說明方法的用途、作用"
notes="方法的備註說明"
其他引數：
tags 操作標籤，非空時將覆蓋value的值
response 響應型別（即返回物件）
responseContainer 宣告包裝的響應容器（返回物件型別）。有效值為 "List", "Set" or "Map"。
responseReference 指定對響應型別的引用。將覆蓋任何指定的response（）類
httpMethod 指定HTTP方法，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position 如果配置多個Api 想改變顯示的順序位置，在1.5版本後不再支援
nickname 第三方工具唯一標識，預設為空
produces 設定MIME型別列表（output），例："application/json, application/xml"，預設為空
consumes 設定MIME型別列表（input），例："application/json, application/xml"，預設為空
protocols 設定特定協議，例：http， https， ws， wss。
authorizations 獲取授權列表（安全宣告），如果未設定，則返回一個空的授權值。
hidden 預設為false， 配置為true 將在文件中隱藏
responseHeaders 響應頭列表
code 響應的HTTP狀態程式碼。預設 200
extensions 擴充套件屬性列表陣列
示例：
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登入檢測", notes="根據使用者名稱、密碼判斷該使用者是否存在")
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}
@ApiImplicitParams：用在請求的方法上，表示一組引數說明
@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
name：引數名，引數名稱可以覆蓋方法引數名稱，路徑引數必須與方法引數一致
value：引數的漢字說明、解釋
required：引數是否必須傳，預設為false [路徑引數必填]
paramType：引數放在哪個地方
· header --> 請求引數的獲取：@RequestHeader
· query --> 請求引數的獲取：@RequestParam
· path（用於restful介面）--> 請求引數的獲取：@PathVariable
· body（不常用）
· form（不常用）
dataType：引數型別，預設String，其它值dataType="Integer"
defaultValue：引數的預設值
示例：
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登入檢測", notes="根據使用者名稱、密碼判斷該使用者是否存在")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "使用者名稱", required = false, paramType = "query", dataType = "String"),
@ApiImplicitParam(name = "pass", value = "密碼", required = false, paramType = "query", dataType = "String")
})
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}
其他引數（@ApiImplicitParam）：
allowableValues 限制引數的可接受值。1.以逗號分隔的列表 2、範圍值 3、設定最小值/最大值
access 允許從API文件中過濾引數。
allowMultiple 指定引數是否可以通過具有多個事件接受多個值，預設為false
example 單個示例
examples 引數示例。僅適用於BodyParameters
@ApiModel：用於響應類上，表示一個返回響應資料的資訊（這種一般用在post建立的時候，使用@RequestBody這樣的場景，請求引數無法使用@ApiImplicitParam註解進行描述的時候）
@ApiModelProperty：用在屬性上，描述響應類的屬性
示例：
@ApiModel(value="使用者登入資訊", description="用於判斷使用者是否存在")
public class UserModel implements Serializable{
private static final long serialVersionUID = 1L;
/**
* 使用者名稱
*/
@ApiModelProperty(value="使用者名稱")
private String account;
/**
* 密碼
*/
@ApiModelProperty(value="密碼")
private String password;
}
其他(@ApiModelProperty)：
value 此屬性的簡要說明。
name 允許覆蓋屬性名稱
allowableValues 限制引數的可接受值。1.以逗號分隔的列表 2、範圍值 3、設定最小值/最大值
access 允許從API文件中過濾屬性。
notes 目前尚未使用。
dataType 引數的資料型別。可以是類名或者引數名，會覆蓋類的屬性名稱。
required 引數是否必傳，預設為false
position 允許在類中對屬性進行排序。預設為0
hidden 允許在Swagger模型定義中隱藏該屬性。
example 屬性的示例。
readOnly 將屬性設定為只讀。
reference 指定對相應型別定義的引用，覆蓋指定的任何引數值
@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
code：數字，例如400
message：資訊，例如"請求引數沒填好"
response：丟擲異常的類
示例：
@ResponseBody
@PostMapping(value="/update/{id}")
@ApiOperation(value = "修改使用者資訊",notes = "開啟頁面並修改指定使用者資訊")
@ApiResponses({
@ApiResponse(code=400,message="請求引數沒填好"),
@ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
})
public JsonResult update(@PathVariable String id, UserModel model){}
@ApiParam： 用在請求方法中，描述引數資訊
name：引數名稱，引數名稱可以覆蓋方法引數名稱，路徑引數必須與方法引數一致
value：引數的簡要說明。
defaultValue：引數預設值
required 屬性是否必填，預設為false [路徑引數必須填]
示例：
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登入檢測", notes="根據使用者名稱、密碼判斷該使用者是否存在")
public UserModel login(@ApiParam(name = "name", value = "使用者名稱", required = false) @RequestParam(value = "name", required = false) String account,
@ApiParam(name = "pass", value = "密碼", required = false) @RequestParam(value = "pass", required = false) String password){}
或以實體類為引數：
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登入檢測", notes="根據使用者名稱、密碼判斷該使用者是否存在")
public UserModel login(@ApiParam(name = "model", value = "使用者資訊Model") UserModel model){}
其他：
allowableValues 限制引數的可接受值。1.以逗號分隔的列表 2、範圍值 3、設定最小值/最大值
access 允許從API文件中過濾引數。
allowMultiple 指定引數是否可以通過具有多個事件接受多個值，預設為false
hidden 隱藏引數列表中的引數。
example 單個示例
examples 引數示例。僅適用於BodyParameters
本文轉載於
愛吃醋的兔子