博客
关于我
强烈建议你试试无所不能的chatGPT,快点击我
swagger2的常用注解
阅读量:6431 次
发布时间:2019-06-23

本文共 3878 字,大约阅读时间需要 12 分钟。

hot3.png

一.

1.关于接口请求类:

@Api(value = "xxx接口",description = "xx接口",tags="xx接口组")

用在controller类上,标识整个类。 tags是分组。

接口请求方法:

@ApiOperation(value = "取消订单")

2.关于方法中请求参数的注解:

如果是一个类对象的话, 该类可以被自动注释。

如果是多个参数可以在方法上加

@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(value="用户controller",tags={"用户操作接口"})@RestControllerpublic 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;  }}

3.model类的注解

@ApiModel("订单请求参数”)public class CyOrder implements Serializable{      private static final long serialVersionUID = 1L;      @ApiModelProperty(value = "门店id")   private String  storeId;
@ApiModel   用于说明类
@ApiModelProperty(value = "结束时间戳 10位",required = true)  用于说明属性

 

 

二.关于返回的说明

 传统的返回数据格式多数是这样:

{  "code":"000",  "message":"成功",  "data":{    "productId":"123",    "productName":"产品名称"  }}
@ApiResponses({        @ApiResponse(code = 400, message = "业务逻辑异常", response = ApiError.class),        @ApiResponse(code = 407, message = "XX异常", response = ApiError.class),        ... ...        @ApiResponse(code = 500, message = "服务器内部错误", response = ApiError.class)})

 

REST风格接口中,一般是这样处理:

如果业务处理成功,HTTP STATUS返回2XX,BODY直接返回业务内容:

{  "productId":"123",  "productName":"产品名称"}

如果业务处理失败,HTTP STATUS返回4XX或5XX,这时才会展现报错信息:

{  "code":"999",  "message":"失败原因"}

业务成功和业务失败,会对外使用两套不同的模型。

Swagger中的展示

Swagger中默认只会展示业务处理成功时的模型:

 

Response Messages中的Response Model不会显示:

 

如果吹毛求疵的话,我们需要将业务失败时模型的内容展示出来,例如这样:

 

注解方式配置

使用注解方式,可以单独为一个API配置Response Model

@ApiResponses({        @ApiResponse(code = 400, message = "业务逻辑异常", response = ApiError.class),        @ApiResponse(code = 407, message = "XX异常", response = ApiError.class),        ... ...        @ApiResponse(code = 500, message = "服务器内部错误", response = ApiError.class)})

这样做的缺点显而易见,每个Controller上都会有一大堆的、重复的@ApiResponses注解,以至于把正常的业务代码淹没。

全局配置

通过Swagger的全局配置,可以自定义默认的Response Model。

首先,在任何一个Controller上,添加至少一个@ApiResponses注解,标明response的类。

@ApiResponses({@ApiResponse(code = 500, message = "服务器内部错误", response = ApiError.class)})

然后,在Swagger配置类的Docket上加入globalResponseMessage

@Beanpublic Docket userApi() {    List
responseMessageList = new ArrayList<>(); responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源").responseModel(new ModelRef("ApiError")).build()); responseMessageList.add(new ResponseMessageBuilder().code(409).message("业务逻辑异常").responseModel(new ModelRef("ApiError")).build()); responseMessageList.add(new ResponseMessageBuilder().code(422).message("参数校验异常").responseModel(new ModelRef("ApiError")).build()); responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("ApiError")).build()); responseMessageList.add(new ResponseMessageBuilder().code(503).message("Hystrix异常").responseModel(new ModelRef("ApiError")).build()); return new Docket(DocumentationType.SWAGGER_2) .globalResponseMessage(RequestMethod.GET, responseMessageList) .globalResponseMessage(RequestMethod.POST, responseMessageList) .globalResponseMessage(RequestMethod.PUT, responseMessageList) .globalResponseMessage(RequestMethod.DELETE, responseMessageList) .build() .apiInfo(apiInfo());}

请注意第一条不能省略,new ModelRef("ApiError"),会查询之前定义@ApiResponse的response中指定的class

 

 

 

转载于:https://my.oschina.net/zhaolin/blog/3050505

你可能感兴趣的文章
Microsoft AJAX Library Cheat Sheet(5): Number和Error类型的扩展
查看>>
AfxGetMainWnd函数
查看>>
WebView增加一个水平Progress,位置、长相随意
查看>>
easyui messager alert 三秒后自动关闭提示
查看>>
带你Python入门,踏进人工智能领域
查看>>
core data 基础操作
查看>>
手机共享电脑网络
查看>>
ORM框架Hibernate (四) 一对一单向、双向关联映射
查看>>
20140616 科技脉搏 -最大颠覆来自创业公司与边缘产业
查看>>
offsetLeft, offsetTop以及postion().left , postion().top有神马区别
查看>>
visual studio 中GIT的用法
查看>>
数据库中触发器before与after认识
查看>>
手动露天广场和立方体
查看>>
随机选择
查看>>
【Java并发编程三】闭锁
查看>>
分布式事务中遇到的 “与基础事务管理器的通信失败”的解决方法
查看>>
让你的Git水平更上一层楼的10个小贴士
查看>>
c++ string 之 find_first_not_of 源码
查看>>
mybatis中的#和$的区别
查看>>
ubuntu下搭建NDK环境
查看>>