Swagger学习及运用（三）--Swagger注解文档及常用参数配置运用_swagger 参数

Swagger注解介绍及常用参数配置与运用

1 @API

    作用于类，放置于controller的一个类上，标志这个类是Swagger资源。资源影响Swagger的根文档、资源列表和该特定资源的API声明。swagger将只包含和声明使用@Api注释的类，而忽略其他资源(servlet等)

1.1 参数

 

1.2 实例代码

@Api(
        tags = "用户",
        description = "User Info Controller"
)
@Controller
@RequestMapping("/user")
public class UserInfoController {
    ...
}

1.3 示例图

 

2 @ApiOperation

    描述API方法，作用于方法上面，放置于标注为@API注解类的方法上，用户表示一个http的请求

2.1 参数

 

2.2 实例代码

@ApiOperation(
    value = "根据ID查找用户信息接口", httpMethod = "GET",
    produces = "application/json",response = Dto.class,
    notes = "根据ID查找用户信息"+
    "<p>成功：success = ‘true’ | 失败：success = ‘false’ 并返回错误码，如下：</p>" +
    "<p>错误码：</p>"+
    "<p>10000 : 用户信息不存在 </p>"
)
@RequestMapping(value="/select/{id}",method = RequestMethod.GET)
@ResponseBody
public Dto<Object> selectUserinfoByid(@PathVariable("id") Integer id){
   Userinfo userinfo = userinfoService.selectUserinfoById(id);
   if(userinfo != null){
       return DtoUtil.returnSuccess("查询用户信息成功");
    }
 
   return DtoUtil.returnFail("用户信息不存在","10000");
 
}

2.3 示例图

 

3 @ApiImplicitParams

    多个参数描述，作用于标注@ApiOperation注解的方法上，解释请求参数里边添加@ApiImplicitParam()注解

3.1 参数

 

3.2 实例代码

    @ApiOperation(
            value = "根据ID查找用户信息接口", httpMethod = "GET",
            produces = "application/json",response = Dto.class,
            notes = "根据ID查找用户信息"+
            "<p>成功：success = ‘true’ | 失败：success = ‘false’ 并返回错误码，如下：</p>" +
            "<p>错误码：</p>"+
            "<p>10000 : 用户信息不存在 </p>"
    )
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", required = true)
    )
    @RequestMapping(value="/select/{id}",method = RequestMethod.GET)
    @ResponseBody
    public Dto<Object> selectUserinfoByid(@PathVariable("id") Integer id){
        Userinfo userinfo = userinfoService.selectUserinfoById(id);
        if(userinfo != null){
            return DtoUtil.returnSuccess("查询用户信息成功");
        }
        return DtoUtil.returnFail("用户信息不存在","10000");
    }

3.3 示例图

 

 

4 @ApiParam

    描述API方法，，作用于标注@ApiOperation注解的方法的参数上，用于参数字段的说明

4.1 参数

 

4.2 实例代码

    @ApiOperation(
            value = "根据ID查找用户信息接口", httpMethod = "GET",
            produces = "application/json",response = Dto.class,
            notes = "根据ID查找用户信息"+
            "<p>成功：success = ‘true’ | 失败：success = ‘false’ 并返回错误码，如下：</p>" +
            "<p>错误码：</p>"+
            "<p>10000 : 用户信息不存在 </p>"
    )
    @RequestMapping(value="/select/{id}",method = RequestMethod.GET)
    @ResponseBody
    public Dto<Object> selectUserinfoByid(@ApiParam(name = "id",value = "用户ID",required = true) @PathVariable("id") Integer id){
        Userinfo userinfo = userinfoService.selectUserinfoById(id);
        if(userinfo != null){
            return DtoUtil.returnSuccess("查询用户信息成功");
        }
        return DtoUtil.returnFail("用户信息不存在","10000");
    }

4.3 示例图

 

5 @ApiModel

    作用于类，对类进行说明，用于实体类接收或者返回

5.1 参数

 

5.2 实例代码

@ApiModel(value = "角色Model",description = "角色表实体对象")
public class Roleinfo {
 
    @ApiModelProperty(
            value = "角色ID",
            name = "roleId",
            dataType = "Integer",
            required = true
    )
    private Integer roleId;
 
    @ApiModelProperty(
            value = "角色名称",
            name = "roleName",
            dataType = "String",
            required = true
    )
}

5.3 示例图

5 @ApiModelProperty

    作用于实体类，用于实体类中某个字段,，用对象接收参数时，描述对象的一个字段

5.1 参数

 

5.2 实例代码

@Api(
        tags = "用户",
        description = "User Info Controller"
)
@Controller
@RequestMapping("/user")
public class UserInfoController {
 
    @Autowired
    private UserinfoService userinfoService;
 
    @ApiOperation(
            value = "新增用户信息接口", httpMethod = "POST",
            produces = "application/json", response = Dto.class,
            notes = "新增用户信息" +
                    "<p>成功：success = ‘true’ | 失败：success = ‘false’ 并返回错误码，如下：</p>" +
                    "<p>错误码：</p>" +
                    "<p>10001 : 添加用户信息失败 </p>"
    )
    @RequestMapping(value = "/insert", method = RequestMethod.POST)
    @ResponseBody
    public Dto<Object> insertUserinfo(Userinfo userinfo){
        int row = userinfoService.insert(userinfo);
        if(row > 0){
            return DtoUtil.returnSuccess("添加用户信息成功");
        }
        return DtoUtil.returnFail("添加用户信息失败", "10002");
    }
}

@ApiModel(value = "用户Model")
public class Userinfo {
 
    @ApiModelProperty(
            value = "用户id",
            name = "id",
            dataType = "Integer",
            required = false
    )
    private Integer userId;
 
    @ApiModelProperty(
            value = "账号",
            name = "userAccount",
            dataType = "String",
            required = true
    )
    private String userAccount;
 
    @ApiModelProperty(
            value = "密码",
            name = "userPassword",
            dataType = "String",
            required = true
    )
    private String userPassword;
 
    @ApiModelProperty(
            value = "用户名",
            name = "userName",
            dataType = "String",
            required = false
    )
    private String userName;
 
    @ApiModelProperty(
            value = "年龄",
            name = "userAge",
            dataType = "Integer"
    )
    private Integer userAge;
 
    ...
    getter and setter
    ...
 
}

5.3 示例图

附件：测试源码

链接：https://pan.baidu.com/s/1N_wxYxJpX5rVF4drF69C_A 
提取码：ew5d