Swagger2一些常用注解
最近遇到了一个使用swagger来生成接口文档的项目，在controller看到了一些没用过的注解（@API、@ApiOperation等），遂记录一下
@API
使用在类上，表明是swagger资源，@API拥有两个属性:value、tags，源码如下
//If tags is not used,this value will be used to set the tag for the operations described by this resource. Otherwise, the value will be ignored.
String value() default '';
//Tags can be used for logical grouping of operations by resources or any other qualifier.
String[] tags() default {''};
生成的api文档会根据tags分类，直白的说就是这个controller中的所有接口生成的接口文档都会在tags这个list下；tags如果有多个值，会生成多个list，每个list都显示所有接口
@Api(tags = '列表1')
@Api(tags = {'列表1','列表2'})
value的作用类似tags,但是不能有多个值
@ApiOperation
使用于在方法上，表示一个http请求的操作
源码中属性太多，记几个比较常用
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）
@ApiParam
使用在方法上或者参数上，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填
@ApiModel()
使用在类上，表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
@ApiModelProperty()
使用在方法，字段上，表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
@ApiParam @PathVariable @RequestParam三者区别
1.@ApiParam 顾名思义，是注解api的参数，也就是用于swagger提供开发者文档，文档中生成的注释内容。
@ApiOperation( value = '编辑公告', notes = '编辑公告', httpMethod = 'POST' )
@RequestMapping( value = '/edit', method = RequestMethod.POST )
public RequestResult edit(
@ApiParam(name = 'title', value = '公告标题', required = true) @RequestParam('title') String title,
@ApiParam(name = 'content', value = '公告内容', required = true) @RequestParam('content') String content){
2.@RequestParam,是获取前端传递给后端的参数，可以是get方式，也可以是post方式。其中如果前端传递的参数和后端你接受的参数起的名字字段是一致的可以省略不写，也可以直接写@RequestParam String title,如果不一致一定要完整写，不然获取不到，如下面的bis_key就必须写。
复制代码
@ApiOperation( value = '编辑公告', notes = '编辑公告', httpMethod = 'POST' )
@RequestMapping( value = '/edit', method = RequestMethod.POST )
public RequestResult edit(
@ApiParam(name = 'bis_key', value = 'bis_key', required = true) String bisKey,
@ApiParam(name = 'title', value = '公告标题', required = true) @RequestParam String title,
@ApiParam(name = 'content', value = '公告内容', required = true) String content,
复制代码
3.@PathVariable，是获取get方式，url后面参数，进行参数绑定
@ApiOperation(value = '删除公告', notes = '删除公告', httpMethod = 'POST')
@RequestMapping(value = '/delete/{bisKey}', method = RequestMethod.POST)
public RequestResult remove(@ApiParam(name = 'bisKey', value = '需要删除的公告ids', required = true) @PathVariable String bisKey) {
pox.xml文件配置：
!--swagger2 start-- dependency groupId io.springfox /groupId artifactId springfox-swagger2 /artifactIdversion 2.4.0 /version/dependency dependency groupId io.springfox /groupId artifactId springfox-swagger-ui /artifactIdversion 2.4.0 /version/dependency !--swagger2 end-- spring boot
配置： parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version1.3.1.RELEASE/version /parent dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency maven项目结构：
在代码的控制类中加入相关的注解
说明：
其中@ApiOperation和@ApiParam为添加的API相关注解，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，描述Controller的作用
@ApiOperation ：描述一个类的一个方法， notes = 接口发布说明）；
其他参数可参考源码；
@ApiParam(required = 是否必须参数， name = 参数名称， value = 参数具体描述）
最常用的5个注解 @Api ：
修饰整个类， httpMethod = 接口请求方式，描述对象的一个字段 其它若干
@ApiResponse ：HTTP响应其中 1 个描述
@ApiResponses ：HTTP响应整体描述
@ApiIgnore ：使用该注解忽略这个API
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
效果图： swagger2 比swagger 不用手动添加swagger的页面 ，或者说一个接口
@ApiParam ：单个参数描述
@ApiModel ：用对象来接收参数
@ApiProperty ：用对象接收参数时，Swagger 让部署管理和使用功能强大的API从未如此简单，。
允许API来始终保持同步。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
Swagger是一个规范和完整的框架，参数和模型紧密集成到服务器端的代码，各参数说明如下： @ApiOperation(value = 接口说明， response = 接口返回参数类型，文件的方法。
上传资源得积分
:sj52abcd
