swagger2 注解使用说明

1.注解说明

注解	作用对象	说明
@Api	controller类	对类的描述
@ApiOperation	接口方法	方法描述
@ApiImplicitParam	接口方法	get单个传参时定义参数描述和是否必传
@ApiImplicitParams	接口方法	get对个传参时定义参数描述和是否必传，需要和@ApiImplicitParam配合使用
@ApiResponse	接口方法	定义返回状态说明，单个参数描述
@ApiResponses	接口方法	定义返回状态说明 ，多个状态描述，需要和@ApiResponse配合使用
@ApiModel	JavaBean类	描述JavaBean用途
@ApiModelProperty	JavaBean类的属性	描述属性的含义，作为传参对象时定义属性是否必传，作为返回对象时定义是否一定有值

2.注解属性说明及使用示例

2.1 @Api

属性名称	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述，1.5.X版本后已经不再使用
basePath	基本路径，1.5.X版本后已经不再使用
position	如果配置多个Api 想改变显示的顺序位置，1.5.X版本后已经不再使用
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏

虽然看着挺多的属性，但是我们平时使用也就无外乎tags、value，下面是使用示例

@Api("登录模块")
@RestController
public class LoginController {


}

2.2 @ApiOperation

属性名称	说明
value	说明方法的作用
notes	方法的备注说明

这个注解的属性还是比较多的，就不一一列出来了，一般常用的也就这两个，给个示例

    @ApiOperation(value = "账号密码登录接口", notes = "通过账号和密码登录")
    @PostMapping("/accountLogin")
    public String accountLogin (@RequestBody LoginVO loginVO) {
        if (!"admin".equals(loginVO)) {
            return "fail";
        }
        if (!"password".equals(loginVO)) {
            return "fail";
        }
        return "success";
    }

2.3 @ApiImplicitParam

属性名称	说明
name	参数名
value	参数的说明、描述
required	参数是否必填
paramType	query	使用@RequestParam 接收的参数
	header	使用@RequestHeader 接收的参数
	path	使用@PathVariable 接收参数
	body	使用 @RequestBody 接收参数
	form	普通表单提交
dataType	参数类型，默认String，其它值dataType="Integer"
defaultValue	参数的默认值

这个注解在平时用的还是很多的，当我们使用@RequestBody传参时一般不用这个注解，可以直接在Javabean的属性上直接加@ApiModelProperty注解，后面也会有讲解，下面是一般使用情形示例

@ApiOperation("验证码登录")
@GetMapping("/validateCodeLogin")
@ApiImplicitParam(name = "validateCode", value = "验证码", required = true, paramType = "query")
public String validateCodeLogin (@RequestParam("validateCode") String validateCode) {
    if (!"validateCode".equals(validateCode)) {
        return "fail";
    }
    return "success";
}

2.4 @ApiImplicitParams

这个主要是解决多个传参而产生的，没啥说的，看下面示例就清楚了

    @ApiOperation("查询指定年龄和性别的用户账号")
    @GetMapping("/findBy")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "age", value = "年龄", required = false, paramType = "query"),
            @ApiImplicitParam(name = "gender", value = "性别", required = true, paramType = "query")
    })
    @ResponseBody
    public List findBy (@RequestParam("age") Integer age, 
                                    @RequestParam("gender") String gender) {
        // TODO 省略查询过程
        return new ArrayList<>();
    }

2.5 @ApiResponse @ApiResponses

属性名称	说明
code	请求返回的状态值，number类型
message	状态描述
response	抛出异常的类

这两个注解其实我在平常使用的不是很多，上个示例吧

    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "传参异常，请检查传参"),
            @ApiResponse(code = 404, message = "url不存在")
    })
    @ApiOperation("验证码登录")
    @GetMapping("/validateCodeLogin")
    @ApiImplicitParam(name = "validateCode", value = "验证码", required = true, paramType = "query")
    public String validateCodeLogin (@RequestParam("validateCode") String validateCode) {
        if (!"validateCode".equals(validateCode)) {
            return "fail";
        }
        return "success";
    }

2.6 @ApiModel

属性名称	说明
value	模型名称
description	模型详细描述
parent	为模型提供超类允许描述继承
discriminator	用于支持多态和继承
subTypes	从此模型继承的子类型的数组。
reference	指定对相应类型定义的引用，覆盖指定的任何其他元数据

这个注解一般用来标记为swgger的解析类，使用示例

@ApiModel(description = "用户信息")
public class UserInfoVO {


}

2.7 @ApiModelProperty

属性名称	说明
value	属性简要说明
name	属性名称
allowableValues	限制此参数的可接受值
access	过滤属性
notes	备用属性，目前未使用
dataType	参数的数据类型
required	参数是否必须有值，作为参数时是否必传，返回参数时是否一定有值
position	排序属性
hidden	是否在Swagger模型定义中隐藏模型属性
example	属性的样本值
readOnly	模型属性指定为只读，不推荐使用
accessMode	指定模型属性的访问模式（AccessMode.READ_ONLY，READ_WRITE）

这个注解用于对属性的说明和校验，接收参数为JSON格式时可以不使用@ApiImplicitParam注解，直接使用使用@ApiModelProperty即可，返回JSON格式时也可以直接被解析。

    @ApiResponse(code = 200, message = "请求成功")
    @ApiOperation(value = "账号密码登录接口", notes = "通过账号和密码登录")
    @PostMapping("/accountLogin")
    public String accountLogin (@RequestBody LoginVO loginVO) {
        if (!"admin".equals(loginVO)) {
            return "fail";
        }
        if (!"password".equals(loginVO)) {
            return "fail";
        }
        return "success";
    }

@ApiModel(description = "用户登录")
public class LoginVO implements Serializable {

    @ApiModelProperty(value = "账号", required = true, allowableValues = "123,456,789")
    private String account;

    @ApiModelProperty(value = "密码", required = true)
    private String password;

    public String getAccount() {
        return account;
    }

    public void setAccount(String account) {
        this.account = account;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

下面接口在yapi上的文档示例

3. 注意事项

• swgger的所有对接口请求的限制都仅仅是显示在文档的，而没有侵入到接口逻辑中，千万不能用来替代业务逻辑使用；
• @ApiModel内的注释不要出现相同，否则会将相同的vo内的字段进行合并；
• @ApiModel的name和value中不能存在字符 ‘ / ’；
• 在请求类型需要根据Rest接口规范来指定请求类型，不能直接使用@RequstMapping，否则会根据Rest规范中的类型全部生成一遍。