Swagger笔记-开发中会用到的部分注解(持续更新)
我的CSDN:https://blog.csdn.net/weixin_43438052/article/details/113705705
Swagger 部分
作用范围 | API | 使用位置 |
---|---|---|
对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
协议集描述 | @Api | 用于controller类上 |
协议描述 | @ApiOperation | 用在controller的方法上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里边 |
非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
分类
用于controller类上:
注解 | 说明 |
---|---|
@Api | 对请求类的说明 |
用于方法上面(说明参数的含义):
注解 | 说明 |
---|---|
@ApiOperation | 方法的说明 |
@ApiImplicitParams、@ApiImplicitParam | 方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明 |
用于方法上面(返回参数或对象的说明):
注解 | 说明 |
---|---|
@ApiResponses、@ApiResponse | 方法返回值的说明 ;@ApiResponses 用于指定单个参数的说明 |
对象类:
注解 | 说明 |
---|---|
@ApiModel | 用在JavaBean类上,说明JavaBean的 用途 |
@ApiModelProperty | 用在JavaBean类的属性上面,说明此属性的的含议 |
@Api
- 标识这个类是
swagger
的资源 - 用于
类
上(主要是放在请求
的类上)- 与
@Controller
或@RestController
并列
- 与
- 说明
该类的作用
,,如用户模块,订单类等
@Api(value = "说明(该参数没什么意义,所以不需要配置)", tags = {"标签"})
value
可以用tags
代替,该参数没什么意义,所以不需要配置tags
如果有多个值,会生成多个list
@Api
其他属性配置:(该部分copy自这里)
属性名称 | 备注 |
---|---|
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 ,将在文档中隐藏 |
- 实例
@Api(value = "品类表", tags = {"category"})
@RestController
@RequestMapping("/category")
public class CategoryController {
}
@ApiOperation
- 用在
方法
上 - 表示
一个http请求的操作
,说明方法的作用
@ApiOperation(value = "接口说明(方法的作用)", httpMethod = "接口请求方式", response = 接口返回参数类型.class, notes = "接口发布说明(方法的备注说明)", tags = {""});
tags
如果有多个值,会生成多个list
。
- 实例
@ApiOperation(value = "获取完整品类信息list", httpMethod = "GET", response = Category.class, notes = "返回的是所有完整的品类信息", tags = {"1","2"})
该部分copy自这里
@ApiImplicitParams:用在请求的方法上,包含一组参数说明 @ApiImplicitParam:对单个参数的说明 name:参数名 value:参数的说明、描述 required:参数是否必须必填 paramType:参数放在哪个地方 · query --> 请求参数的获取:@RequestParam · header --> 请求参数的获取:@RequestHeader · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(请求体)--> @RequestBody User user · form(普通表单提交) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值
@ApiParam
- 用于
方法
上 参数
或字段
的说明
@ApiParam(required = false, name = "参数名称", value = "参数具体描述")
required
:是否必须参数
false
true
- 实例
@ApiOperation(value = "新增品类", httpMethod = "POST", notes = "必须,传入json格式数据", tags = {"category","insert"})
@PostMapping("addNewCategory")
public ResultVO addNewCategory(@ApiParam(required = true, name = "json", value = "json格式,必须,非空") @RequestBody Category category) {
return ResultVO.ok(categoryService.addNewCategory(category));
}
@ApiModel
- 用于
类
- 表示对
类
进行说明、描述
@ApiModel(value = "对象名", description = "描述")
value
、description
都可以省略
- 实例
@ApiModel(value = "salesHistory对象", description = "销售记录表salesHistory")
public class SalesHistory {
}
@ApiModel
的用途有2个:
- 当请求数据描述,即
@RequestBody
时, 用于封装请求(包括数据的各种校验)数据;- 当响应值是对象时,即
@ResponseBody
时,用于返回值对象的描述。实例:
- 当请求数据描述时,
@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省略 }
@Api(tags="用户模块") @Controller public class UserController { @ApiOperation(value = "用户登录", notes = "") @PostMapping(value = "/login") public R login(@RequestBody UserLoginVO userLoginVO) { User user=userSerivce.login(userLoginVO); return R.okData(user); } }
- @ApiModelProperty:用在JavaBean类的属性上面,说明属性的含义
@ApiModel(description= "返回响应数据") public class RestMessage 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 略*/ }
@ApiModelProperty
- 用于
方法
- 对
参数
、字段
的描述
@ApiModelProperty(required = false, value = "字段说明", name = "重写 属性名称", dataType = "重写 属性类型", example = "举例说明", hidden = false)
required
:是否必须参数
false
true
hidden
:是否隐藏
false
true
- 实例
@ApiModel(value = "salesHistory对象", description = "销售记录表salesHistory")
public class SalesHistory {
@ApiModelProperty(required = true, value = "销售记录id", name = "id", example = "zu_xt_202101011324")
private Long id;
@ApiModelProperty(required=true, value="状态", name="state")
private Integer state;
}
@ApiIgnore
- 用于
方法
、方法
- 可以被swagger
不显示在页面上
没啥好演示的,自个实践……
@ApiImplicitParam
-
对
单个参数的说明
-
作用范围:
非对象参数描述
-
用于
方法
(用在controller
的方法
上) -
表示单独的请求参数
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据,(用于restful 接口--> 请求参数的获取:@PathVariable ) |
|
query | 直接跟参数完成自动映射赋值 | |
body | (请求体),以流的形式提交,仅支持POST |
|
header | 参数在request headers 里边提交 |
|
form | (普通表单提交),以form表单的形式提交,仅支持POST |
|
dataType | 参数的数据类型 只作为标志说明,并没有实际验证 | |
String | 默认 | |
Long | ||
Integer | ||
name | 参数名 | |
value | 参数的意义、描述 | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 参数的默认值 |
- 实例
@ApiOperation("查询测试")
@GetMapping("select")
@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
public void select(){
}
@ApiImplicitParams
-
作用范围:
非对象参数集
-
用于
方法
(用在controller
的方法
上) -
包含
一组参数说明
,表示多个
单独的请求参数,即包含多个@ApiImplicitParam
-
实例
@ApiOperation("查询测试")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
public void select(){
}
@ApiResponse
- 每个参数的说明
code
:数字,例如400message
:信息,例如"请求参数没填好"response
:抛出异常的类
- 作用范围:
Response
- 用在
@ApiResponses
里
@ApiResponses
-
方法返回对象的说明
-
作用范围:
Response集
-
用在
controller
的方法
上 -
即包含多个
@ApiResponse
-
实例(例子来源于网络)
@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);
}
}
参考资料
[1] https://blog.csdn.net/xiaojin21cen/article/details/78654652
💥 一个正在学习全栈的 💥
⭐ 精神小伙 ⭐
💥 MelodyJerry 💥