2021-01-14

Swagger常用注解

Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring项目

实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，

同时swagger-ui还可以测试spring Restful风格的接口功能。

@ApiOperation不是spring自带的注解是swagger里的
com.wordnik.swagger.annotations.ApiOperation;

@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）；其他参数可参考源码；
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”）

实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。

@ApiImplicitParam：
作用在方法上，表示单独的请求参数
参数：

1. name ：参数名。
2. value ： 参数的具体意义，作用。
3. required ： 参数是否必填。
4. dataType ：参数的数据类型。
5. paramType ：查询参数类型，这里有几种形式：

类型 作用
path 以地址的形式提交数据
query 直接跟参数完成自动映射赋值
body 以流的形式提交 仅支持POST
header 参数在request headers 里边提交
form 以form表单的形式提交 仅支持POST

@ApiIgnore 可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。
1、作用在类上时，整个类都会被忽略，隐藏某个类还可以用@Api注解自带的hidden属性，当hidden为true时，该类隐藏
2、当作用在方法上时，方法将被忽略，隐藏某个方法还可以用@APIOperation注解自带的hidden属性，当hidden为true时，该类隐藏
3、作用在参数上时，单个具体的参数会被忽略
4、 在实体类中忽略不需要字段的方式：
（1）用@ApiModelProperty注解自带的hidden属性
（2）使用@JsonIgnore注解

---

以下不是Swagger注解
@Valid
用于验证注解是否符合要求，直接加在变量user之前，在变量中添加验证信息的要求，当不符合要求时
就会在方法中返回message 的错误提示信息。

spring-boot中可以用@validated来校验数据，如果数据异常则会统一抛出异常，方便异常中心统一处理。

@ApiModelProperty用法 :
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明 name–属性名字 dataType–重写属性类型 required–是否必填 hidden–隐藏
如图: