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放到你想 ...
随机推荐
- IP数据包格式与ARP转发原理
一.网络层简介1.网络层功能2.网络层协议字段二.ICMP与封装三.ARP协议与ARP欺骗1.ARP协议2.ARP欺骗 1.网络层功能 1. 定义了基于IP地址的逻辑地址2. 连接不同的媒介3. 选择 ...
- Caffeine缓存的简单介绍
1.简介 在本文中,我们将了解Caffeine,一个用于Java的高性能缓存库. 缓存和Map之间的一个根本区别是缓存会清理存储的项目. 一个清理策略会决定在某个给定时间哪些对象应该被删除,这个策略直 ...
- [刘阳Java]_美团点评2018届校招面试总结_Java后台开发【转载】
美团喜欢一口气把三轮技术面和HR面一起面完,虽然身心比较累(每一面差不多一个小时),不过也算是一个好事,不像某些公司一天就一面然后让回去等消息,等面试通知也等得让人很焦虑,而且还容易出现面试时间冲突. ...
- 如何监控 Log4j2 异步日志遇到写入瓶颈
如何监控 Log4j2 异步日志遇到写入瓶颈 在之前的一篇文章中(一次鞭辟入里的 Log4j2 异步日志输出阻塞问题的定位),我们详细分析了一个经典的 Log4j2 异步日志阻塞问题的定位,主要原因还 ...
- Lesson 12 Life on a desert island
Lesson 12 Life on a desert island desert island ['dezət 'ailənd] n. 荒岛 uninhabited island coral isla ...
- java跨平台性说明
一.举例说明 我们知道,只要是用标准C开发的程序,使用不同的编译器编译后的可执行文件是可以在对应平台运行的,比如windows可以使用VC编译,那编译后的exe文件就可以在windows下运行:liu ...
- js中的 true 与 false
可判断为 false 的情况: 0,-0,NaN,undedined,"",false,null,缺省的值 可判断为 true 的情况: 除false的其他情况均可,包括负数.&q ...
- 添加底部导航栏tabbar
效果图: 如果要添加底部导航栏,最少2个,最多5个. app.json { "pages": [ "pages/index/index", "page ...
- 高德开放平台实现批量自定义marker和信息窗体显示
上篇博客提到云图无法实现文本标签标记marker,这篇博客着重实现在marker点文本标记以及自定义按钮窗体显示. 1.效果: 2.代码实现 <!doctype html> <htm ...
- 走心的中级Android工程师跳槽经验分享
这些经验是我最近四个月,从准备面试到找到合适工作的汗水和泪水,希望对你们能有帮助! define 跳槽 跳槽前要思考的问题 钱不到位怎么办 心委屈怎么办 离职前的思考 确定要走时需要做的准备 行情怎么 ...