這里只講述@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 指定對相應類型定義的引用，覆蓋指定的任何參數值