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:字符串,参数值示例;
微信赞赏
支付宝赞赏
常见问题FAQ
- 免费下载或者VIP会员专享资源能否直接商用?
- 本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用者承担。更多说明请参考 VIP介绍。
- 提示下载完但解压或打开不了?
- 找不到素材资源介绍文章里的示例图片?
- 关于编程知识分享网(www.ittce.com)