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")})@ResponseBodypublic List<UserInfoVO> 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规范中的类型全部生成一遍。