Swagger2 | 03. Swagger2的注释

0. 使用的项目名字：test_spring_boot

模块名字：test_swagger

传送门 == 》码云仓库

1. 可用注释

1.1. Swagger2注释

正常启动swagger，如果没有配置注释，那么界面应该是全英文

接口的可读性较低

因此需要添加一些注释：

注释	作用	使用位置
@ApiModel	为Model添加注释	在entity的类代码上使用这个注解
@ApiModelProperty(value = “xxx”,example= “yyy”)	为Model的属性添加注释	在entity的属性上使用这个注解
@ApiOpration(“xxx”)	为controller的方法添加注释	在controller中的方法上使用这个注解
@ApiParam(“xxx”)	为controller的方法的参数添加注释	在controller中的方法中的参数前使用这个注解
@ApiResponses({@ApiResponse(code = 1,message= “xxx”),})	这里采用集合的方式，可以指定用以指定状态码和对应的信息解释code：状态码，message：信息解释	在controller的方法上使用这个注解

目前大部分朋友使用的Swagger2版本为2.9.2，该版本下

@ApiModelProperty中的example属性要写，否则在以下情形会报错：

属性是Integer时：此时example为 “”,但是在进行解析时会尝试将其解析为int，此时会报错（不影响使用，但控制台会变得很乱）

1.2. 拓展知识

（1）类的属性为对象时

entity的类代码上有这样一个注解：

@JsonIgnoreProperties(value = {"handler"})

如果不使用这个注解，在controller返回一个对象，且这个对象有一个对象属性时，就会报错，因为无法正常解析这个对象属性。

在主类的类代码上使用该注解即可（A类有一个属性，该属性是B类，那么A类就是主类）

（2）在接口上不要用@RequestMapping

如果使用@RequestMapping，那么同一个接口会列出POST、GET、DELETE、PUT等请求方式的多个接口

2. 效果展示

3. 接口测试

可以直接在swagger中进行测试：