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 

Logo
CSDN学习社区

CSDN联合极客时间，共同打造面向开发者的精品内容学习社区，助力成长！

更多推荐

cover

Kaldi之父，IEEE Fellow，小米首席语音科学家Daniel Povey将出席2024全球机器学习技术大会并发表演讲！

avatar CSDN学习社区
cover

探索神经网络在商品销售和图像识别中的应用

avatar CSDN学习社区
cover

基于stm32F103的座面声控台灯

avatar CSDN学习社区