常用到的注解有:

作用范围 API 使用位置
协议集描述 @Api 用于controller类上
协议描述 @ApiOperation 用在controller的方法上
非对象参数集 @ApiImplicitParams 用在controller的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边
对象参数描述 @ApiParam 用在@ApiImplicitParams的方法里边,定义接收的参数形式
描述返回对象的意义 @ApiModel 用在返回对象类上
对象属性 @ApiModelProperty 用在参数对象的字段上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses里边
Response @ResponseHeader  

1. @Api标记

Api 用在类上,说明该类的作用。可以标记一个 Controller 类做为 swagger 文档资源,使用方式:

与Controller注解并列使用。 属性配置

属性名称 备注 是否弃用
value url的路径值  
tags 如果设置这个值、value的值会被覆盖  
description 对api资源的描述 @Deprecated
basePath 基本路径可以不配置 @Deprecated
position 如果配置多个Api 想改变显示的顺序位置 @Deprecated
produces For example, "application/json, application/xml"  
consumes For example, "application/json, application/xml"  
protocols Possible values: http, https, ws, wss.  
authorizations 高级特性认证时配置  

在SpringMvc中的配置如下:

@RestController
@RequestMapping(value = "/app/table")
@Api(value = "/app/table", protocols = "http")
public class AppTableController { }

2. @ApiOperation标记

ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

@ApiOperation(
value = "Find purchase order by ID",
notes = "",
response = A.class,
tags = {""})

与Controller中的方法并列使用。

属性配置:

属性名称 备注 是否弃用
value url的路径值  
tags 如果设置这个值、value的值会被覆盖  
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置 @Deprecated
produces For example, "application/json, application/xml"  
consumes For example, "application/json, application/xml"  
protocols Possible values: http, https, ws, wss.  
authorizations 高级特性认证时配置  
hidden 配置为true 将在文档中隐藏  
response 返回的对象  
responseContainer 这些对象是有效的 "List", "Set" or "Map".,其他无效  
responseReference 指定对响应类型的引用。指定的引用可以是本地的,也可以是远程的*将按原样使用,并覆盖任何指定的response()类。  
responseHeaders 响应旁边提供的可能标题列表。  
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"  
code http的状态码 默认 200  
extensions 扩展属性  
notes 注释说明  
response 方法的返回值的类型class  

在SpringMvc中的配置如下:

@ApiOperation(value = "/createCode", notes = "创建文件", response = ResultObj.class)
@RequestMapping(value = "/createCode")
public ResultObj createCode(
@RequestParam(value = "tab_name", required = true) String tab_name
, @RequestParam(value = "type", required = true) Integer type
, @RequestParam(value = "includeSwagger", required = true) Boolean includeSwagger
, @RequestParam(value = "moduleName", required = true) String moduleName
, @RequestParam(value = "packageName", required = true) String packageName) {
return ResultObj.getDefaultResponse(appTableService.listTable(tab_name, null));
}

3. @ApiImplicitParams、@ApiImplicitParam、@ApiParam标记

@ApiImplicitParams

只有value一个属性,用来装多个@ApiImplicitParam

@ApiImplicitParam

用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

属性名称 备注
paramType 参数放在哪个地方
name 参数名称
value 参数代表的含义
dataType 参数类型
dataTypeClass 参数类型
required 是否必要
defaultValue 参数的默认值
paramType:
header-->请求参数的获取:@RequestHeader(代码中接收注解)
query-->请求参数的获取:@RequestParam(代码中接收注解)
path(用于restful接口)-->请求参数的获取:@PathVariable(代码中接收注解)
body-->请求参数的获取:@RequestBody(代码中接收注解)
form(不常用))
使用方式
@ApiOperation(value = "/createCode", notes = "创建文件", response = ResultObj.class)
@ApiImplicitParams({
@ApiImplicitParam(name = "表名", value = "tab_name", paramType = "query", dataType = "String", required = true)
, @ApiImplicitParam(name = "生成代码类别参数", value = "type", paramType = "query", dataType = "Integer", required = true)
})
@RequestMapping(value = "/createCode")
public ResultObj createCode(
@RequestParam(value = "tab_name", required = true) String tabName
, @RequestParam(value = "type", required = true, defaultValue = "-1") Integer type){return null;}
@ApiParam

用在接收参数中,指定一个请求参数的信息

属性名称 备注
name 要绑定到的请求参数的名称
value 参数的简单描述
required 是否必要
defaultValue 参数的默认值

具体参考文档v1.5.0

@ApiParam请求属性,使用方式:与Controller中的方法并列使用。

属性配置:

属性名称 备注
name 属性名称
value 属性值
defaultValue 默认属性值
allowableValues 可以不配置
required 是否属性必填
access 不过多描述
allowMultiple 默认为false
hidden 隐藏该属性
example 举例子

在SpringMvc中的配置如下:

 public ResponseEntity<Order> getOrderById(
@ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
@PathVariable("orderId") String orderId)

4. @ApiModel、@ApiModelProperty

@ApiModel

描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用 @ApiImplicitParam注解进行描述的时候;

属性名称 备注
value 名称
description 描述
parent 父类 (class)
discriminator 官方描述:支持模型继承和多态性。这是用作鉴别器的字段名。基于这个领域,可以断言需要使用哪种子类型。
subTypes 子类型 {(class)}
reference 官方描述:指定对相应类型定义的引用,覆盖指定的任何其他元数据
@ApiModelProperty

描述一个model的属性。

@Table(name = "app_table", schema = "", catalog = "")
@ApiModel(value = "物理表信息表", description = "当前数据库表信息")
public class AppTable implements Serializable { private static final long serialVersionUID = -1L; @Id
@Column(name = "tab_name", unique = true)
@ApiModelProperty(value = "表名主键")

5. @ApiResponses、@ApiResponse

@ApiResponses:响应集配置,使用方式:
 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。 属性配置:

属性名称 备注
value 多个ApiResponse配置

在SpringMvc中的配置如下:

 @RequestMapping(value = "/order", method = POST)
@ApiOperation(value = "Place an order for a pet", response = Order.class)
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
public ResponseEntity<String> placeOrder(
@ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
storeData.add(order);
return ok("");
}
@ApiResponse:响应配置,使用方式:
@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。 属性配置:

属性名称 备注
code http的状态码
message 描述
response 默认响应类 Void
reference 参考ApiOperation中配置
responseHeaders 参考 ResponseHeader 属性配置说明
responseContainer 参考ApiOperation中配置

在SpringMvc中的配置如下:

 @RequestMapping(value = "/order", method = POST)
@ApiOperation(value = "Place an order for a pet", response = Order.class)
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
public ResponseEntity<String> placeOrder(
@ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
storeData.add(order);
return ok("");
}

6. ResponseHeader

响应头设置,使用方法

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。 属性配置:

属性名称 备注
name 响应头名称
description 头描述
response 默认响应类 Void
responseContainer 参考ApiOperation中配置

Swagger2.X注解的更多相关文章

  1. swagger2常用注解

    常用注解: @Api()用于类: 表示标识这个类是swagger的资源 @ApiOperation()用于方法: 表示一个http请求的操作 @ApiParam()用于方法,参数,字段说明: 表示对参 ...

  2. Swagger2常用注解和使用方法

    一   引入maven依赖 <!--整合Swagger2--> <dependency> <groupId>com.spring4all</groupId&g ...

  3. Swagger2常用注解解析(轻松构建Swagger)

    Swagger2常用注解解析 一.SpringBoot集成Swagger2 二.常用注解解析 具体使用举例说明: 一.SpringBoot集成Swagger2 引入相关jar包 <!-- swa ...

  4. swagger2 常用注解的使用

    一.@Api 效果: @Api注解放在类上面,这里的value是没用的,tags表示该controller的介绍. 二 .@ApiOperation 效果: @ApiOperation注解用于放在方法 ...

  5. Swagger2基本注解使用

    @Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置&q ...

  6. Swagger2常用注解及其说明 (转)

    Api 用在Controller中,标记一个Controller作为swagger的文档资源 属性名称 说明 value Controller的注解 description 对api资源的描述 hid ...

  7. swagger2常用注解说明

    说明: 1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4) 2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行 ...

  8. swagger2 常用注解说明

    常用到的注解有: Api ApiModel ApiModelProperty ApiOperation ApiParam ApiResponse ApiResponses ResponseHeader ...

  9. Swagger2 @ApiIgnore注解忽略接口在swagger-ui.html中显示

    果项目中定义了一个controller,但是我们又不想把这个接口在swagger-ui.html中体现出来怎么办?不要着急,Swagger2已经替我们想到了这个问题,只要把@ApiIgnore放到你想 ...

随机推荐

  1. [刘阳Java]_SpringMVC文件上传第1季_第10讲

    今天来介绍一个关于SpringMVC框架的文件上传功能.首先我个人感觉SpringMVC框架的文件上传还是要比Struts2框架要好用一些,灵活性更强.因为SpringMVC框架的文件上传有几种不同的 ...

  2. aria2+uget+chrome

    1.安装aira2 sudo apt install aria2 2.安装及配置uget sudo apt install uget 编辑 -> 设置: 分类 -> 属性: 3.chrom ...

  3. python基础之文件的读取

    #文件名 txt文件的读取#文件的读取 open("文件","读写方法") with open("文件","读写方法") ...

  4. 微信小程序云开发-数据库-商品列表数据排序

    一.wxml添加升序和降序 在商品列表的wxml文件中添加超链接a标签,分别用于升序和降序的点击.分别绑定升序和降序的点击事件. 二.js文件实现升序和降序 分别写对应的按价格升序函数sortByPr ...

  5. 微信小程序云开发-添加数据

    一.数据的添加 使用add方法添加数据 添加完成后,在数据库中查询,可以看到数据库中添加了1条数据,此时添加的数据系统自动添加了_openid 将[添加]功能写到对应的方法中 wxml页面中,点击[添 ...

  6. SpringBoot之yaml语法及静态资源访问

    配置文件-yaml 在spring Boot开发中推荐使用yaml来作为配置文件. 基本语法: key: value:kv之间有空格 大小写敏感 使用缩进表示层级关系 缩进不允许使用tab,只允许空格 ...

  7. python验证码图片生成

    环境:win10(64位)+pycharm2018+pillow5.4+python3.7 对Django的跨站请求保护的有所了解的同学会知道{%csrf_token%}在实际上作用并不是那么大,只要 ...

  8. Capture One 21 Pro 14.0.2.36中文版安装教程

    Capture One 21 Pro 14.0.2.36 for windows是一款由丹麦PHASE ONE飞思公司推出的.非常专业强大的图像处理编辑工具. 下载 Capture One 21 Pr ...

  9. HashMap的转化时机

    HashMap的转化时机 /** * 使用红黑树(而不是链表)来存放元素.当向至少具有这么多节点的链表再添加元素时,链表就将转换为红黑树. * 该值必须大于2,并且应该至少为8,以便于删除红黑树时转回 ...

  10. Dubbo 实现一个Load Balance (用于灰度发布)

    Dubbo 可以实现的扩展很多, 官方文档在这: https://dubbo.apache.org/zh/docs/v2.7/dev/impls/ (太简单了....) 下面我们实现一个Load Ba ...