Swagger2 java项目中注解的用法和图解

写在前面

swagger作为前端和后端的工具，作为一个后端开发人员，有几点必须要注意的。

• 1、在编写实体类的时候，一定要注意实体填写的完整，例如 规定位置 position 和 example 这是一个非常良好的习惯
• 2、在编写controller层的时候，要注意 get 和 post 的区别。已经参数是在 路径上 或者 作为请求参数 或者 方法体 或者 表单，这些对于swagger2都是有区别的。建议区分好。如果是 参数在路径上或者作为请求参数，最后带上 example，说明这个参数的作用和demo
• 3、一个写得优秀的swagger势必需要很多时间，但是这些时间可以让前后端少了更多沟通，毕竟写代码的都喜欢安静写代码，这些乱七八糟的沟通， 就交给swagger吧

一、Swagger注解

作用范围	API	使用位置
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
对象参数描述	@ApiParam	用在@ApiImplicitParams的方法里边，定义接收的参数形式
描述返回对象的意义	@ApiModel	用在返回对象类上
对象属性	@ApiModelProperty	用在参数对象的字段上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
Response	@ResponseHeader	~

二、entity 实体类 的swagger2注解

2.1 @ApiModel

用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用
@ApiImplicitParam注解进行描述的时候）

类上
@ApiModel(value = “用户实体类”,description = “用户描述用户的字段”)

2.2 @ApiModelProperty

用在属性上，描述响应类的属性

字段上（注意一定要加上 position 不然可能出现json解析乱码的情况）
@ApiModelProperty(value = “更新时间”,position = 16,example = “2020-01-01 00:00:00”)

三、Controller 的swagger2注解

3.1 @Api

类上
@Api(tags = “用户对象”, description = “注册用户、增删改查用户对象”)

3.2 @ApiOperation

方法上
@ApiOperation(“新增用户”)

3.3 @ApiImplicitParams

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

注意：要区分 query普通参数，既？拼接路径。 path路径上的参数，从上下文获取。body方法体，在方法体上设置参数