Swagger与JSR-303的联合作战

使用场景

在永辉新零售相关系统的日常研发过程中, 通常伴随着前后端的接口交互. 传统文档性质的接口说明, 需要定期手动维护, 因此实时性方面存在缺陷, 接口文档年久失修的情况也经常存在. 为了解决这个问题, 研发团队引入了Swagger. 下面几点, 是我们团队Swagger的定位:

Swagger能够帮助服务端开发人员, 在写代码的同时, "顺便"在API上加入相应的注解, 即可完成接口说明, 不需要再写接口文档.

项目发布到测试环境后(生产环境默认关闭Swagger), Swagger会自动生成接口说明页面. 前端开发人员只需打开相应的页面, 就能看到完整的接口说明, 同时还能够轻松访问接口, 获得反馈.

Swagger虽然不是一个高大上的技术, 但它却是能够解决某个研发痛点的一个好工具.

接入Swagger

引入依赖包

增加配置信息

增加对JSR-303注解的支持

对于前端的接口请求, 服务端通常会首先校验请求参数的合法性, 永辉云创服务端团队使用JSR-303通过注解的方式简洁地进行参数校验. (JSR-303这里不作扩展, 感兴趣的读者, 可以自己上网查阅资料). API接口文档需要说明对前端请求参数的要求. 从而引申出Swagger对JSR-303注解整合的需求. 效果如下图(Swagger生产的API文档)所示, 我们将鼠标放在传参定义的字段上面, 即可显示JSR-303注解定义的参数要求.

在应用主类上增加插件

申明API接口

使用@ApiOperation说明API接口

@Validated注解标记要JSR-303校验的对象，通常一个对象会在多个接口上使用，这时，为了不同接口使用不同的校验规则，需要在注解内设置value值(即分组)

@ApiOperation是Swagger对接口的说明

image.png | left | 747x329

使用@ApiModel，@ApiModelProperty说明传参

@NotNull，@Max等是JSR-303的标准注释，用于校验参数是否满足需要。groups是将校验规则分组，这样一个VO对象被不同的接口方法使用可以指定不同的分组校验规则。（我们实践发现group容易造成接口定义混乱，所以我们没有使用group, 而是针对每个接口使用一个专属VO对象）

@ApiModel，@ApiModelProperty是swaggerUI的注解，用于swaggerUI前端显示

image.png | left | 747x430

Swagger与JSR-303

Swagger注解作用域为API接口文档(不会影响应用程序执行行为), JSR-303注解的作用域为应用程序的参数校验. 例如以下注解, 即使Swagger注解中加入了required=true属性,程序也不会校验. 如果需要校验,应使用JSR-303注解.

Swagger注解

JSR-303注解

提供给外部的接口, 如果需要进行参数校验,使用JSR-303规范的注解形式.

@Null(message="参数错误: 不能为空") 注解中的message属性必填, message用于在校验失败时, 系统抛出的异常信息.

Swagger不支持JSR-303的@NotNull,@Null注解(API文档不会显示是否可以为空). 可以那个Swagger注解的required属性来满足需要: @ApiModelProperty(value="id",required=true)

THANK YOU

Powered by 永辉云创技术

关注我们，共同进步