swagger註解作用
阿新 • • 發佈:2018-12-11
註解
@Api:
作用在類上,用來標註該類具體實現內容。表示標識這個類是swagger的資源 。 引數: 1. tags:可以使用tags()允許您為操作設定多個標籤的屬性,而不是使用該屬性。 2. description:可描述描述該類作用。
@ApiImplicitParam:
作用在方法上,表示單獨的請求引數 引數: 1. name :引數名。 2. value : 引數的具體意義,作用。 3. required : 引數是否必填。 4. dataType :引數的資料型別。 5. paramType :查詢引數型別,這裡有幾種形式:
型別 | 作用 |
---|---|
path | 以地址的形式提交資料 |
query | 直接跟引數完成自動對映賦值 |
body | 以流的形式提交 僅支援POST |
header | 引數在request headers 裡邊提交 |
form | 以form表單的形式提交 僅支援POST |
在這裡我被坑過一次:當我發POST請求的時候,當時接受的整個引數,不論我用body還是query,後臺都會報Body Missing錯誤。這個引數和SpringMvc中的@RequestBody衝突,索性我就去掉了paramType,對介面測試並沒有影響。
@ApiImplicitParams:
用於方法,包含多個 @ApiImplicitParam: 例:
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
@ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
- 1
- 2
- 3
@ApiModel:
用於類,表示對類進行說明,用於引數用實體類接收;
@ApiModelProperty:
用於方法,欄位 ,表示對model屬性的說明或者資料操作更改 例:
@ApiModel(value = "User", description = "使用者")
public class User implements Serializable{
private static final long serialVersionUID = 1546481732633762837L;
/**
* 使用者ID
*/
@ApiModelProperty(value = "使用者ID", required = true)
@NotEmpty(message = "{id.empty}", groups = {Default.class,New.class,Update.class})
protected String id;
/**
* code/登入帳號
*/
@ApiModelProperty(value = "code/登入帳號")
@NotEmpty(message = "{itcode.empty}", groups = {Default.class,New.class,Update.class})
protected String itcode;
/**
* 使用者姓名
*/
@ApiModelProperty(value = "使用者姓名")
@NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
protected String name;
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
@ApiOperation:
用於方法,表示一個http請求的操作 。
@ApiOperation(value = "獲取圖書資訊", notes = "獲取圖書資訊", response = Book.class, responseContainer = "Item", produces = "application/json")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
@ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
@ResponseBody
public Book getBook(@PathVariable Long id, String date) {
return books.get(id);
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
@ApiResponse:
用於方法,描述操作的可能響應。
@ApiResponses:
用於方法,一個允許多個ApiResponse物件列表的包裝器。 例:
@ApiResponses(value = {
@ApiResponse(code = 500, message = "2001:因輸入資料問題導致的報錯"),
@ApiResponse(code = 500, message = "403:沒有許可權"),
@ApiResponse(code = 500, message = "2500:通用報錯(包括資料、邏輯、外來鍵關聯等,不區分錯誤型別)")})
- 1
- 2
- 3
- 4
@ApiParam:
用於方法,引數,欄位說明,表示對引數的新增元資料(說明或是否必填等)
宣告要在資源或操作上使用的授權方案。
介紹一個OAuth2授權範圍。
@ResponseHeader:
響應頭設定,使用方法。