swagger2.4注解大全

1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4)
2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行集成完成)

官网WIKI
常用注解:
– @Api()用于类;
表示标识这个类是swagger的资源
– @ApiOperation()用于方法;
表示一个http请求的操作
– @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等)
– @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收
– @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改
– @ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略
– @ApiImplicitParam() 用于方法
表示单独的请求参数
– @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam

具体使用举例说明:
@Api()
用于类;表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
但是tags如果有多个值,会生成多个list

@Api(value=”用户controller”,tags={“用户操作接口”})
@RestController
public class UserController { }
效果图:

@ApiOperation() 用于方法;表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组(视情况而用)
@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
name–参数名
value–参数说明
required–是否必填

@Api(value=”用户controller”,tags={“用户操作接口”})
@RestController
public class UserController { @ApiOperation(value=”获取用户信息”,tags={“获取用户信息copy”},notes=”注意问题点”) @GetMapping(“/getUserInfo”) public User getUserInfo(@ApiParam(name=”id”,value=”用户id”,required=true) Long id,@ApiParam(name=”username”,value=”用户名”) String username) { // userService可忽略,是业务逻辑 User user = userService.getUserInfo(); return user; } }
效果图:

@ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

@ApiModel(value=”user对象”,description=”用户对象user”)
public class User implements Serializable{ private static final long serialVersionUID = 1L; @ApiModelProperty(value=”用户名”,name=”username”,example=”xingguo”) private String username; @ApiModelProperty(value=”状态”,name=”state”,required=true) private Integer state; private String password; private String nickName; private Integer isDeleted; @ApiModelProperty(value=”id数组”,hidden=true) private String[] ids; private List<String> idList; //省略get/set }
@ApiOperation(“更改用户信息”)
@PostMapping(“/updateUserInfo”)
public int updateUserInfo(@RequestBody @ApiParam(name=”用户对象”,value=”传入json格式”,required=true) User user){ int num = userService.updateUserInfo(user); return num; }
效果图:

 

@ApiIgnore()用于类或者方法上,可以不被swagger显示在页面上
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

@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(){ }
效果图:

 

 

 

 

 

 

 

 

@Api 标识一个java类型是文档类,用controller类的类名上

@ApiModel 表示一个实体类/模型文档,用在类名上;

@ApiModelProperty 作用在属性上,添加属性描述;

@ApiOperation 作用在接口类的方法上,控制方法的相关描述;

@ApiImplicitParam 作用在接口方法上,描述单个参数信息,只能作用在方法上;

@ApiImplicitParams 作用在接口方法上,@ApiImplicitParam参数组;

@ApiParam 作用在接口方法上,描述单个参数信息,属性基本与@ApiImplicitParam一样,但可以作用在方法、参数、属性上;

下面分别对每个注解的常用参数作讲解。

@Api:

value:字符串,对controller类的作用描述,代替原来的description(已过时),一般用此属性;

tags:字符串数组,标签组,同样可以描述controller的作用;

@ApiModel

value:字符串,模型的简短别名,使得在文档的导航中便于识别;

description:字符串,模型的附加描述;

@ApiOperation

value:字符串,方法的功能描述;

tags:字符串数组,标签组,同样可以描述方法的作用;

response:ClassType,显示指出返回的对象类型;在响应示例中会显示出改对象的字段以及示例、描述;

code:响应代码,默认200,一般不改;

@ApiModelProperty

value:字符串,字段描述;

required:boolean;指定参数是否必须,默认false;

example:字符串,参数值的示例

@ApiImplicitParam

name:字符串,参数名;

value:字符串,参数描述;

defaultValue:字符串,参数默认值;

required:boolean,标识是否必须传值,默认false;

dataType:字符串,参数类型,可以是某个类名,也可以是基本数据类型的引用类名,如Integer;

example:字符串,参数值示例;

@ApiImplicitParams

value:@ApiImplicitParam类型数组,当方法有多个@ApiImplicitParam参数时,需要放到@ApiImplicitParams注解中

@ApiParam

name:字符串,参数名;

value:字符串,参数描述;

defaultValue:字符串,设置默认值;

required:boolean,是否必须,默认false;

example:字符串,参数值示例;

赞赏

微信赞赏支付宝赞赏

编程知识分享网,一个有趣的平台!
编程知识分享网ittce.com » swagger2.4注解大全

常见问题FAQ

免费下载或者VIP会员专享资源能否直接商用?
本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用者承担。更多说明请参考 VIP介绍。
提示下载完但解压或打开不了?
最常见的情况是下载不完整: 可对比下载完压缩包的与网盘上的容量,若小于网盘提示的容量则是这个原因。这是浏览器下载的bug,建议用百度网盘软件或迅雷下载。若排除这种情况,可在对应资源底部留言,或 联络我们.。
找不到素材资源介绍文章里的示例图片?
对于PPT,KEY,Mockups,APP,网页模版等类型的素材,文章内用于介绍的图片通常并不包含在对应可供下载素材包内。这些相关商业图片需另外购买,且本站不负责(也没有办法)找到出处。 同样地一些字体文件也是这种情况,但部分素材会在素材包内有一份字体下载链接清单。
关于编程知识分享网(www.ittce.com)
编程知识分享网,一个有趣的平台,小心有毒!

发表评论

  • 22会员总数(位)
  • 123资源总数(个)
  • 8本周发布(个)
  • 0 今日发布(个)
  • 1204稳定运行(天)

提供最优质的资源集合

立即查看 了解详情
升级SVIP尊享更多特权立即升级