swagger注解的理解

swagger注解的理解

1、@Api：表示标识这个类是swagger的资源

@Api  用在请求的类上，表示对类的说明
  tags="说明该类的作用，可以在UI界面上看到的注解"
  value="该参数没什么意义，只是帮助自己理解，在UI界面上也看到，所以不需要配置"
  description="该参数用来对类进行描述"
  hidden="配置为true 将在文档中隐藏"

示例：

@Api(value = "用户信息接口",tags="此为用户信息接口") 
@Api(value = "角色信息", description = "角色信息")

标签的配置效果如下：

2、@ApiOperation：表示一个http请求的操作

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="接口发布说明"
    httpMethod = "接口请求方式"
    response = "接口返回参数类型"

示例：

@ApiOperation(value = "添加角色信息--value值", notes = "添加角色信息",httpMethod = "GET")

配置效果如下

注意： 如果@ApiOperation中httpMethod的请求方式和@RequestMapping中method的请求方式不同，swagger则优先读取@ApiOperation中的请求方式

3、@ApiParam() 用于方法，参数，字段说明

@ApiParam() 表示对参数的添加元数据（说明或是否必填等）
	name="参数名"
	value="参数说明"
	required="是否必填"

示例：

@ApiParam(name="id",value="角色主键",required = true)
@ApiModelProperty(hidden = true)  //hidden=true则在swagger页面中不会显示该字段

配置效果如下：

目前未在页面中看到name值的展示效果
注意： 该注解如果用于实体类的方法中，则涉及该类的所有接口，对应的属性都会受相关的控制

4、@ApiModel()用于类

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
	value="表示对象名"
	description="描述"
	都可省略

设置的值在页面中未显示

5、@ApiModelProperty() 用于方法，字段

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

示例：

@ApiModelProperty(value = "角色名称", name="name2",dataType = "Java.lang.Integer")

效果如下：

只有value值起作用，其他的未起作用，待神UR了解

6、@ApiIgnore() 用于类，方法，方法参数

表示这个方法或者类被忽略
可以不被swagger显示在页面上

7、 @ApiImplicitParam() 用于方法

表示单独的请求参数

8、@ApiImplicitParams() 用于方法，包含多个

	name="参数ming"
	value="参数说明"
	dataType="数据类型"
	paramType="参数类型"
	example="举例说明"

9、@RequestMapping() 用于类、方法

此注解为spring的注解非swagger注解

value="指定请求的实际地址，指定的地址可以是URI Template 模式"
method="指定请求的method类型， GET、POST、PUT、DELETE等"
consumes="指定处理请求的提交内容类型（Content-Type），例如application/json, text/html"
produces="指定返回的内容类型，仅当request请求头中的(Accept)类型中包含该指定类型才返回"
params="指定request中必须包含某些参数值是，才让该方法处理"
headers="指定request中必须包含某些指定的header值，才能让该方法处理请求"

此处需要注意的是，用swagger展示接口时，该参数的method或者@ApiOperation注解的httpMetod必须指定一个，否则同一个请求会展示出7中不同方式的接口