转自： Swagger2 最全注解说明 - h3399
文章目录
1,swagger2 注解整体说明
2,@API: 请求类的说明
3,@ApiOperation: 方法的说明
3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明
4,@ApiResponses,@ApiResponse: 方法返回值的说明
5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息
5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义
1,swagger2 注解整体说明
用于 controller 类上:
用于方法上面 (说明参数的含义):
用于方法上面 (返回参数或对象的说明):
对象类:
2,@API: 请求类的说明
@API: 放在 请求的类上, 与 @Controller 并列, 说明类的作用, 如用户模块, 订单类等.
- tags="说明该类的作用"
- value="该参数没什么意义, 所以不需要配置"
示例:
- @API(tags="订单模块")
- @Controller
- public class OrderController {
- }
@API 其它属性配置:
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注解详解（swagger2的常用注解）的文章就介绍到这了,更多相关内容请继续浏览下面的相关推荐文章，希望大家都能在编程的领域有一番成就！版权声明：
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！
转载请注明出处，原文链接：https://www.xkablog.com/rfx/16451.html