swagger2 注解说明
文章目录
- 1、maven依赖
- 2、swagger2 注解整体说明
- 2.1、请求类的描述
- 2.2、方法和方法参数的描述
- 2.3、方法的响应状态的描述
- 2.4、对象的描述
- 3、请求类的描述
- 3.1、@Api:请求类的说明
- 3.2、示例:
- 4、方法和方法参数的描述
- 4.1、@ApiOperation:方法的说明
- 4.2、@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
- 4.3、示列:
- 5、响应状态的描述
- 5.1、@ApiResponses、@ApiResponse:响应状态状态的说明
- 5.2、 示例:
- 6、对象的描述
- 6.1、@ApiModel:对象的整体说明
- 6.2、@ApiModelProperty 对象中每个参数的说明
- 6.3、示例:
- 1)入参是对象,即 `@RequestBody` 时, 用于封装请求
- 2)返回值是对象,即 `@ResponseBody` 时,用于返回值对象的描述。
- 3) UserLoginVO 和 JsonResult 的使用
- 6.4、swagger2 中查看:
- 7、默认的地址
1、maven依赖
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version>
</dependency>
(注:当前2018年,请使用最新的依赖)
2、swagger2 注解整体说明
2.1、请求类的描述
注解 | 说明 |
---|---|
@Api | 对请求类的说明 |
2.2、方法和方法参数的描述
注解 | 说明 |
---|---|
@ApiOperation | 方法的说明 |
@ApiImplicitParams | 方法参数的说明; |
@ApiImplicitParam | 用于指定单个参数的说明。 |
2.3、方法的响应状态的描述
注解 | 说明 |
---|---|
@ApiResponses | 方法返回值的说明 ; |
@ApiResponse | 用于指定单个参数的说明。 |
2.4、对象的描述
注解 | 说明 |
---|---|
@ApiModel | 用在JavaBean类上,说明JavaBean的 整体用途 |
@ApiModelProperty | 用在JavaBean类的属性上面,说明此属性的的含议 |
3、请求类的描述
3.1、@Api:请求类的说明
@Api:放在 请求的类上。与 @Controller 并列,说明类的作用,如用户模块,订单类等。tags="说明该类的作用"value="该参数没什么意义,所以不需要配置"
3.2、示例:
@Api(tags="订单模块")
@Controller
public class OrderController {}
@Api
其它属性配置:
属性名称 | 备注 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | 如, “application/json, application/xml” |
consumes | 如, “application/json, application/xml” |
protocols | 协议类型,如: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true ,将在文档中隐藏 |
4、方法和方法参数的描述
4.1、@ApiOperation:方法的说明
@ApiOperation:"用在请求的方法上,说明方法的作用"value="说明方法的作用"notes="方法的备注说明"
4.2、@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明@ApiImplicitParam:对单个参数的说明 name:参数名value:参数的说明、描述required:参数是否必须必填paramType:参数放在哪个地方· query --> 请求参数的获取:@RequestParam· header --> 请求参数的获取:@RequestHeader · path(用于restful接口)--> 请求参数的获取:@PathVariable· body(请求体)--> @RequestBody User user· form(普通表单提交) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值
4.3、示列:
@Api(tags="用户模块")
@Controller
public class UserController {@ApiOperation(value="用户登录",notes="随边说点啥")@ApiImplicitParams({@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")})@PostMapping("/login")public JsonResult login(@RequestParam String mobile, @RequestParam String password, @RequestParam Integer age){//...return JsonResult.ok(map);}
}
5、响应状态的描述
5.1、@ApiResponses、@ApiResponse:响应状态状态的说明
@ApiResponses:响应状态的说明。是个数组,可包含多个 @ApiResponse@ApiResponse:每个参数的说明code:数字,例如400message:信息,例如"请求参数没填好"response:抛出异常的类
5.2、 示例:
@Api(tags="用户模块")
@Controller
public class UserController {@ApiOperation("获取用户信息")@ApiImplicitParams({@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")}) @ApiResponses({@ApiResponse(code = 200, message = "请求成功"),@ApiResponse(code = 400, message = "请求参数没填好"),@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")}) @ResponseBody@RequestMapping("/list")public JsonResult list(@RequestParam String userId) {...return JsonResult.ok().put("page", pageUtil);}
}
6、对象的描述
6.1、@ApiModel:对象的整体说明
@ApiModel
经常用于请求的入参对象和 响应返回值对象的描述。
- 入参是对象,即
@RequestBody
时, 用于封装请求(包括数据的各种校验)数据; - 返回值是对象,即
@ResponseBody
时,用于返回值对象的描述。
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {}
6.2、@ApiModelProperty 对象中每个参数的说明
@ApiModelProperty 用于每个属性上面,说明属生的含义。
@ApiModel
public class UserLoginVO implements Serializable {@ApiModelProperty(value = "用户名",required=true) private String username;
}
6.3、示例:
1)入参是对象,即 @RequestBody
时, 用于封装请求
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {private static final long serialVersionUID = 1L;@ApiModelProperty(value = "用户名",required=true) private String username;@ApiModelProperty(value = "密码",required=true) private String password;// getter/setter省略
}
2)返回值是对象,即 @ResponseBody
时,用于返回值对象的描述。
@ApiModel(description= "返回响应数据")
public class JsonResult implements Serializable{@ApiModelProperty(value = "是否成功",required=true)private boolean success=true; @ApiModelProperty(value = "错误码")private Integer errCode;@ApiModelProperty(value = "提示信息")private String message;@ApiModelProperty(value = "数据")private Object data;/* getter/setter 略*/
}
3) UserLoginVO 和 JsonResult 的使用
UserLoginVO 作为入参对象。
JsonResult 作为返回值对象。
@Api(tags="用户模块")
@Controller
public class UserController {@ApiOperation(value = "用户登录", notes = "")@ResponseBody@PostMapping(value = "/login")public JsonResult login(@RequestBody UserLoginVO userLoginVO) {User user=userSerivce.login(userLoginVO);return new JsonResult("1","成功");}
}
6.4、swagger2 中查看:
7、默认的地址
http://localhost:5680/zxmall/swagger-ui.html
swagger2 注解说明相关推荐
- SpringFox Swagger2注解基本用法
一切参数说明,参考官方API文档:http://docs.swagger.io/swagger-core/current/apidocs/index.html?io/swagger/annotatio ...
- swagger2 注解
刚开始的时候,在controller层使用@RequestParam的时候,发现这个参数是必须要输入值的,但是我们有时候必须查询的时候允许参数为空,使用这个注解就不行了. 在集成了swagger2后, ...
- swagger2 注解说明 ( @ApiImplicitParams )
@Api:用在请求的类上,表示对类的说明tags="说明该类的作用,可以在UI界面上看到的注解"value="该参数没什么意义,在UI界面上也看到,所以不需要配置&quo ...
- swagger2注解说明文档
注解 属性 说明 @Api 用于类上,说明该类的作用.可以标记一个controller类作为swagger的文档资源 value url的路径 tags 如果设置这个值,value的值会被覆盖 des ...
- swagger2 注解说明文档
注解 属性 备注 @Api 用于类上,说明该类的作用.可以标记一个Controller类做为swagger 文档资源 示例: @Api(value = "xxx", descrip ...
- swagger2注解详细说明
@Api:用在请求的类上,表示对类的说明tags="说明该类的作用,可以在UI界面上看到的注解"value="该参数没什么意义,在UI界面上也看到,所以不需要配置&quo ...
- Swagger2 最全注解说明(转载)
转自: Swagger2 最全注解说明 - h3399 Swagger2 最全注解说明 文章目录 1,swagger2 注解整体说明 2,@API: 请求类的说明 3,@ApiOperation: 方 ...
- SpringBoot+Mybatis+Swagger2环境搭建
点击上方"方志朋",选择"设为星标" 回复"666"获取新整理的面试资料 作者:calebman https://www.jianshu.c ...
- Spring Boot(九)Swagger2自动生成接口文档和Mock模拟数据
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
- 从零搭建一个 Spring Boot 开发环境!Spring Boot+Mybatis+Swagger2 环境搭建
从零搭建一个 Spring Boot 开发环境!Spring Boot+Mybatis+Swagger2 环境搭建 本文简介 为什么使用Spring Boot 搭建怎样一个环境 开发环境 导入快速启动 ...
最新文章
- palm基础----7 获取系统信息
- nginx出现404和403错误
- mysql平均值函数保留两位小数点_用sql的avg(score)求完平均值后,保存两位小数的方法(用于查询或视图)...
- java 多线程压测_java多线程Jmeter压测实现
- “命令终端”的实现4-优化之解耦
- SpringCloud工作笔记038---spring cloud微服务权限认证_终于确定下来大体的思想了
- 网页在兼容模式和急速模式下前者报错、后者正常的原因查找
- YaoLingJump开发者日志(四)
- 创建一个带有Lookup字段的List
- try catch finally return
- Actionscript 3.0 迁移指南
- java系列视频教程下载
- ES6阮一峰笔记部分对象新增方法、字符串的扩展和新增方法
- 已删除的好友微信号怎么找回来
- 【最受欢迎最容易理解的初阶c语言教学】4.操作符和常见关键字
- Gram矩阵和核函数
- python计算平均值标准差和中位数_如何使用python求平均数、方差、中位数
- Effective前端6:避免页面卡顿
- ipv6一致性(packet too big)测试
- java移动平均线算法_移动平均线的原理是什么? 移动平均线计算公式详解
热门文章
- 常用原型图绘制工具比较
- Ubuntu下截图工具推荐
- 传奇服务器修改二级密码,找回传奇玩家账号和二级密码,修改密码和密保
- Oracle 临时表空间 SQL语句
- Java 中的十大排序算法
- 嫡权法赋权法_赋权法_
- matlab方差 anov,MATLAB单因素方差分析
- HTMLpre代码美化
- 【3dmax千千问】食住玩初学3dmax插件神器第24课:3dmax自学渲染效果图教程|疯狂模渲大师、室内设计师、效果图绘图员都应该如何认识VRAY或扫描线CORONA渲染器及其VR核心算法的作用?
- 气压传动PLC控制机械手臂实验实训台,QY-QDSY01