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	方法	例子