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:
作用在方法上,表示单独的请求参数
参数:
- name :参数名。
- value : 参数的具体意义,作用。
- required : 参数是否必填。
- dataType :参数的数据类型。
- 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–隐藏
如图: