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

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

1 @API

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

1.1 参数

参数名称	说明	类型	默认值	备注
tags	说明	Sting	""	当tags为""或者未指定使用默认值时，显示为@API标注的类名，如UserInfoController显示为user-info-controller
description	描述	String	""	当description为""或者未指定使用默认值时，显示为@API标注的类名，如UserInfoController显示为User Info Controller

 

1.2 实例代码

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

1.3 示例图

 

2 @ApiOperation

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

2.1 参数

参数名称	说明	类型	默认值	备注
value	方法说明	String	""	必填
httpMethod	请求方法	String	""
produces	输出类型	String	""
response	返回类型	Class<?>	java.lang.Void.class
notes	方法描述详情	String	""

 

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 参数

参数名称	说明	类型	默认值	备注
name	参数名称	String	""	当name使用""后者未指定使用默认值时，显示为参数指定的参数名
value	参数描述	String	""	当value使用""后者未指定使用默认值时，显示为参数指定的参数名
paramType	参数类型	String	""	当paramType使用""后者未指定使用默认值时，根据参数的实际来源显示，如果来源于请求路径则显示为path
require	是否必需	boolean	false

 

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 参数

参数名称	说明	类型	默认值	备注
name	参数名称	String	""	当name使用""后者未指定使用默认值时，显示为参数指定的参数名
value	参数描述	String	""	当value使用""后者未指定使用默认值时，显示为参数指定的参数名
required	是否必需	boolean	false

 

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 参数

参数名称	说明	类型	默认值	备注
value	对象名	String	""
description	对象描述	String	""

 

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 参数

参数名称	说明	类型	默认值	备注
value	参数解释	String	""
name	参数名称	String	""
dataType	属性类型	String	""
required	是否必填	boolean	false
example	示例	String
hidden	隐藏	boolean	fasle

 

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