Swagger2 最全注解说明(转载)
Swagger2 最全注解说明
@Data
@ApiModel("系统用户分页查询请求体")
public class SysUserPageQueryRequest extends BasePageRequest {
//@Serial
private static final long serialVersionUID = -7586253215056854970L;
@ApiModelProperty("创建时间开始")
@JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")
private Date createTimeStart;
@ApiModelProperty("创建时间结束")
private Date createTimeEnd;
}
文章目录
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
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 没有源码,如何修改代码逻辑?
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· NetPad:一个.NET开源、跨平台的C#编辑器
· PowerShell开发游戏 · 打蜜蜂
2022-12-28 linux 查看系统配置