Swagger註解使用方法

1. @Api

註解名稱	註解屬性	作用域	屬性作用
@Api	tags	類	說明該類的作用
	value	類	說明該類的作用

舉個🌰：

@Api(value = "用戶類控制器",tags="用戶類控制器")
public class UserController {
...
}

2 . @ApiOperation

註解名稱	註解屬性	作用域	屬性作用
@ApiOperation()	value	方法	描述方法作用
	notes	方法	提示內容
	tags	方法	分組

舉個🌰：   

@ApiOperation(value = "獲取用戶列表",notes = "獲取用戶列表")
public List<User> get() {
     ...   
}

 

3. @ApiParam

註解名稱	註解屬性	作用域	屬性作用
@ApiParam()	name	方法參數	參數名
	value	方法參數	參數說明
	required	方法參數	是否必填

舉個🌰：    

@ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息")
public User get(@ApiParam(name="id",value="用戶id",required=true) Long id) {
    log.info("GET..{}...方法執行。。。",id);
    return userService.getById(id);
}

 

4. @ApiModel && @ApiModelProperty

註解名稱	註解屬性	作用域	屬性作用
@ApiModel()	value	類	對象名
	description	類	描述
@ApiModelProperty()	value	方法	字段說明
	name	方法	屬性名
	dataType	方法	屬性類型
	required	方法	是否必填
	example	方法	舉例
	hidden	方法	隱藏

舉個🌰：

@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(value = "用戶ID",example = "1000001",hidden=true)
    private Long id;

    @ApiModelProperty(value="用戶名",required = true,dataType = "String")
    private String userName;

    @ApiModelProperty(value = "密碼")
    private String password;
}

 

5. @ApiImplicitParam && @ApiImplicitParams

@ApiImplicitParam可以單個用於方法之上，多個參數的話可以把@ApiImplicitParam放到@ApiImplicitParams中，這裏只羅列@ApiImplicitParam的屬性：

註解名稱	註解屬性	作用域	屬性作用
@ApiImplicitParam()	value	方法	參數說明
	name	方法	參數名
	dataType	方法	數據類型
	paramType	方法	參數類型
	example	方法	舉例

舉個🌰：

    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用戶實體user", required = true, dataType = "User")
    })
    public void put(User user) {
        userService.updateById(user);
        log.info("PUT方法執行。。。");
    }

 

這裏需要注意一點，我們並沒有在註解中寫圖中圈中的兩個參數，這個是去讀取了我們剛剛爲User類的註解，並將用戶名設置爲必填！

6.@ApiResposne && @ApiResponses

@ApiResponses與@ApiResponse的關係和@ApiImplicitParam && @ApiImplicitParams 的關係和用法都是類似的

註解名稱	註解屬性	作用域	屬性作用
@ApiResponse()	response	方法	返回類
	code	方法	返回碼
	message	方法	返回信息
	examples	方法	例子