转自： Swagger2 最全注解说明 - h3399

Swagger2 最全注解说明

文章目录

1,swagger2 注解整体说明

2,@API: 请求类的说明

3,@ApiOperation: 方法的说明

3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明

4,@ApiResponses,@ApiResponse: 方法返回值的说明

5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息

5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

1,swagger2 注解整体说明

用于 controller 类上:

注解	说明
@Api	对请求类的说明

用于方法上面 (说明参数的含义):

注解	说明
@ApiOperation	方法的说明
@ApiImplicitParams、@ApiImplicitParam	方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明

用于方法上面 (返回参数或对象的说明):

注解	说明
@ApiResponses、@ApiResponse	方法返回值的说明；@ApiResponses 用于指定单个参数的说明

对象类:

注解	说明
@ApiModel	用在 JavaBean 类上，说明 JavaBean 的用途
@ApiModelProperty	用在 JavaBean 类的属性上面，说明此属性的的含议

2,@API: 请求类的说明

@API: 放在请求的类上, 与 @Controller 并列, 说明类的作用, 如用户模块, 订单类等.

tags="说明该类的作用"
value="该参数没什么意义, 所以不需要配置"

示例:

@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 ，将在文档中隐藏

3,@ApiOperation: 方法的说明

@ApiOperation:"用在请求的方法上, 说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"

3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明

@ApiImplicitParams: 用在请求的方法上, 包含一组参数说明

@ApiImplicitParam: 对单个参数的说明

name: 参数名

value: 参数的汉字说明, 解释

required: 参数是否必须传

paramType: 参数放在哪个地方

. header --> 请求参数的获取:@RequestHeader

. query --> 请求参数的获取:@RequestParam

. path(用于 restful 接口)--> 请求参数的获取:@PathVariable

. body(请求体)--> @RequestBody User user
. form(普通表单提交)

dataType: 参数类型, 默认 String, 其它值 dataType="Integer"

defaultValue: 参数的默认值

示列:

@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);
}
}

4,@ApiResponses,@ApiResponse: 方法返回值的说明

@ApiResponses: 方法返回对象的说明

@ApiResponse: 每个参数的说明

code: 数字, 例如 400

message: 信息, 例如 "请求参数没填好"

response: 抛出异常的类

示例:

@API(tags="用户模块")
@Controller
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户 Id")
})
@ApiResponses({
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
...
return JsonResult.ok().put("page", pageUtil);
}
}

5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息

@ApiModel: 用于 JavaBean 的类上面, 表示此 JavaBean 整体的信息

(这种一般用在 post 创建的时候, 使用 @RequestBody 这样的场景,

请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )

5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

示例:

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{
@ApiModelProperty(value = "是否成功")
private boolean success=true;
@ApiModelProperty(value = "返回对象")
private Object data;
@ApiModelProperty(value = "错误编号")
private Integer errCode;
@ApiModelProperty(value = "错误信息")
private String message;
/* getter/setter 略 */
}

来源: http://www.bubuko.com/infodetail-3289545.html

Swagger2 最全注解说明（转载）相关推荐

Spring3.2.0-mybatis3.2.0 基于全注解搭建的后台框架-基础版
2019独角兽企业重金招聘Python工程师标准>>> 摘要: Spring3.2.0-mybatis3.2.0 基于全注解搭建的后台框架-基础版没有什么不可能之前一直用的是自 ...
spring-102-spring全注解快速实现事务
之前使用jdbc操作数据库,并使用事务的时候是这样操作: Connection connection = null;try {//connection = getConnection(....);// ...
基于全注解的SpringMVC+Spring4.2+hibernate4.3框架搭建
概述从0到1教你搭建spring+springMVC+hibernate整合框架,基于注解. 本教程框架为基于全注解的SpringMVC+Spring4.2+hibernate4.3,开发工具为my ...
2.3.3 spring属性注入-注解注入-全注解-配置类扫描
代码: spring2-属性注入-全注解-配置类扫描.zip - 蓝奏云文件大小:12.3 K|https://www.lanzouw.com/iPK5vvq21uf 这个博客,我们使用全注解的方式来 ...
mybatis使用全注解的方式案例（包含一对多关系映射）
前面我写过ssh:ssh(Spring+Spring mvc+hibernate)简单增删改查案例和ssm:ssm(Spring+Spring mvc+mybatis)的案例,需要了解的可以去看看, ...
java spring mvc_java spring mvc 全注解
本人苦逼学生一枚,马上就要毕业,面临找工作,实在是不想离开学校.在老师的教导下学习了spring mvc ,配置文件实在繁琐,因此网上百度学习了spring mvc 全注解方式完成spring的装配工 ...
Spring中使用XML方式导入Spring配置文件，Boot中使用全注解导入Spring配置
目录 Spring中的方法 Spring Boot中的方法 Spring中的方法 @ImportResource:导入Spring的配置文件,让配置文件里面的内容生效: Spring Boot里面没有 ...
Andriod界面设计的分辨率和尺寸适配全攻略转载
Andriod界面设计的分辨率和尺寸适配全攻略转载 2016年09月27日 17:45:56 第一.屏幕尺寸: 一般表示是手机的实际物理尺寸,屏幕尺寸指屏幕的对角线的长度,单位是英寸,1英寸=2.5 ...
SpringMVC全注解环境搭建
源代码: 链接:https://pan.baidu.com/s/1Lxb-riH–YQNIy3c0i8pFA 提取码:y3aq 文档地址:https://shphuang_aliyun.gitee.i ...

Swagger2 最全注解说明（转载）

Swagger2 最全注解说明

Swagger2 最全注解说明（转载）相关推荐

最新文章

热门文章