SwaggerAPI註解詳解,以及註解常用參數配置

官網github地址：https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X

註解

@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")})

@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;

@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);
    }

@ApiResponse：

用於方法，描述操作的可能響應。

@ApiResponses：

用於方法，一個允許多個ApiResponse對象列表的包裝器。
例：

@ApiResponses(value = { 
            @ApiResponse(code = 500, message = "2001:因輸入數據問題導致的報錯"),
            @ApiResponse(code = 500, message = "403:沒有權限"),
            @ApiResponse(code = 500, message = "2500:通用報錯（包括數據、邏輯、外鍵關聯等，不區分錯誤類型）")})

@ApiParam：

用於方法，參數，字段說明，表示對參數的添加元數據（說明或是否必填等）

@Authorization：

聲明要在資源或操作上使用的授權方案。

@AuthorizationScope：

介紹一個OAuth2授權範圍。

@ResponseHeader：

響應頭設置，使用方法。