Swagger2.X注解
常用到的注解有:
作用范围 | 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注解的更多相关文章
- swagger2常用注解
常用注解: @Api()用于类: 表示标识这个类是swagger的资源 @ApiOperation()用于方法: 表示一个http请求的操作 @ApiParam()用于方法,参数,字段说明: 表示对参 ...
- Swagger2常用注解和使用方法
一 引入maven依赖 <!--整合Swagger2--> <dependency> <groupId>com.spring4all</groupId&g ...
- Swagger2常用注解解析(轻松构建Swagger)
Swagger2常用注解解析 一.SpringBoot集成Swagger2 二.常用注解解析 具体使用举例说明: 一.SpringBoot集成Swagger2 引入相关jar包 <!-- swa ...
- swagger2 常用注解的使用
一.@Api 效果: @Api注解放在类上面,这里的value是没用的,tags表示该controller的介绍. 二 .@ApiOperation 效果: @ApiOperation注解用于放在方法 ...
- Swagger2基本注解使用
@Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置&q ...
- Swagger2常用注解及其说明 (转)
Api 用在Controller中,标记一个Controller作为swagger的文档资源 属性名称 说明 value Controller的注解 description 对api资源的描述 hid ...
- swagger2常用注解说明
说明: 1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4) 2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行 ...
- swagger2 常用注解说明
常用到的注解有: Api ApiModel ApiModelProperty ApiOperation ApiParam ApiResponse ApiResponses ResponseHeader ...
- Swagger2 @ApiIgnore注解忽略接口在swagger-ui.html中显示
果项目中定义了一个controller,但是我们又不想把这个接口在swagger-ui.html中体现出来怎么办?不要着急,Swagger2已经替我们想到了这个问题,只要把@ApiIgnore放到你想 ...
随机推荐
- [刘阳Java]_SpringMVC文件上传第1季_第10讲
今天来介绍一个关于SpringMVC框架的文件上传功能.首先我个人感觉SpringMVC框架的文件上传还是要比Struts2框架要好用一些,灵活性更强.因为SpringMVC框架的文件上传有几种不同的 ...
- aria2+uget+chrome
1.安装aira2 sudo apt install aria2 2.安装及配置uget sudo apt install uget 编辑 -> 设置: 分类 -> 属性: 3.chrom ...
- python基础之文件的读取
#文件名 txt文件的读取#文件的读取 open("文件","读写方法") with open("文件","读写方法") ...
- 微信小程序云开发-数据库-商品列表数据排序
一.wxml添加升序和降序 在商品列表的wxml文件中添加超链接a标签,分别用于升序和降序的点击.分别绑定升序和降序的点击事件. 二.js文件实现升序和降序 分别写对应的按价格升序函数sortByPr ...
- 微信小程序云开发-添加数据
一.数据的添加 使用add方法添加数据 添加完成后,在数据库中查询,可以看到数据库中添加了1条数据,此时添加的数据系统自动添加了_openid 将[添加]功能写到对应的方法中 wxml页面中,点击[添 ...
- SpringBoot之yaml语法及静态资源访问
配置文件-yaml 在spring Boot开发中推荐使用yaml来作为配置文件. 基本语法: key: value:kv之间有空格 大小写敏感 使用缩进表示层级关系 缩进不允许使用tab,只允许空格 ...
- python验证码图片生成
环境:win10(64位)+pycharm2018+pillow5.4+python3.7 对Django的跨站请求保护的有所了解的同学会知道{%csrf_token%}在实际上作用并不是那么大,只要 ...
- Capture One 21 Pro 14.0.2.36中文版安装教程
Capture One 21 Pro 14.0.2.36 for windows是一款由丹麦PHASE ONE飞思公司推出的.非常专业强大的图像处理编辑工具. 下载 Capture One 21 Pr ...
- HashMap的转化时机
HashMap的转化时机 /** * 使用红黑树(而不是链表)来存放元素.当向至少具有这么多节点的链表再添加元素时,链表就将转换为红黑树. * 该值必须大于2,并且应该至少为8,以便于删除红黑树时转回 ...
- Dubbo 实现一个Load Balance (用于灰度发布)
Dubbo 可以实现的扩展很多, 官方文档在这: https://dubbo.apache.org/zh/docs/v2.7/dev/impls/ (太简单了....) 下面我们实现一个Load Ba ...