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中不同方式的接口

已标记关键词 清除标记
相关推荐
©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页