Swagger2参数使用相同对象展示不同参数的实现
研发背景
在我们正常的spring web框架下请求参数与响应参数使用的有许多相同的对象,当我们引入swagger2框架后,每个接口的参数(请求/响应)都会包含所有的字段。
解决办法一
有人也许使用过@JsonIgnoreProperties或@JsonIgnore进行参数的排除,这些注解有一个弊端,会影响所有的JSON序列化问题,并且所有使用此参数对象的接口都会排除使用该注解的字段。
解决办法二
还有一种做法是每个接口参数都使用单独的VO类,这种方式其中一个问题是项目中存在着大量的VO类来适应文档,并且VO类进入项目后需要进行单独转换为对应的业务需要的对象,如果参数量或层级比较大的话,此转换工作量比较大,并且与项目的耦合性也是比较高的。
新的解决办法
经历了种种方案后,作者的做法是使用注解进行分类参数。接下来我们看一下具体的使用方式。
新框架的使用
快速开始
说明
项目github地址:https://github.com/weiguangfu/springfox-swagger2-plus
目前扩展的swagger2版本为:2.7.0、2.8.0、2.9.1、2.9.2
对应扩展的最新版本为:2.7.0-1-beta4、2.8.0-1-beta2、2.9.1-1-beta2、2.9.2-1-beta2
接下来以2.7.0进行举例
版本说明
由于swagger2的版本增强的方式不同,所以我定义的版本与swagger2的版本是一一对应的。例如:swagger2的版本为2.7.0,对应的版本为2.7.0-X-X方式。
更新说明
更新说明地址:https://github.com/weiguangfu/springfox-swagger2-plus/blob/master/update.md
- 2.7.0-1-beta2
项目加入Travis-CI持续集成.
项目源码路径由com.weiguangfu.swagger2.plus变更为cn.weiguangfu.swagger2.plus, 与groupId保持一致.
完善文档, 增加swagger2对应swagger-ui版本的依赖, 此版本后, 引用项目不需要在单独引入swagger-ui依赖. - 2.7.0-1-beta4, 2.8.0-1-beta2, 2.9.2-1-beta2, 2.9.1-1-beta2
修改参数中有层级管理(继承)时报错问题. - 2.7.0-1 (临时发布字段必填的版本, 待稳定后将发布其他对应版本)
增加注解 @ApiRequestFieldRequired 可以标注文档字段是否为必填字段.
配置文件错误修复: 启用Swagger增强配置由原 swagger.push.enable 变更为 swagger.plus.enable, 为不影响原版本使用, 原配置依然可以使用, 优先使用 swagger.plus.enable .
maven依赖引入
默认引入springfox-swagger2-plus项目时自动引入swagger2对应的版本. springfox-swagger-ui也会自动被引入.
<dependency>
<groupId>cn.weiguangfu</groupId>
<artifactId>springfox-swagger2-plus</artifactId>
<version>2.7.0-1</version>
</dependency>
配置文件开启Swagger2增强
此配置为了适应配置文件方式的profile, 可以配置停用线上swagger2的增强
# 此配置标志着开启增强, 目的是为了可以屏蔽线上Swagger2增强.
# 不编辑此配置或者值为enable: false则不开启Swagger2增强.
swagger:
plus:
enable: true
开启API增强
仅增加@EnableSwagger2Plus注解在原Swagger2的配置类上即可,其他配置与swager2原配置相同。
/**
* @EnableSwagger2Plus注解标志着开启Swagger2Plus,
* 此注解同时开启Swagger2的注解.
*/
@Configuration
@EnableSwagger2Plus
public class Swagger2Config {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).groupName("push-test")
.apiInfo(new ApiInfoBuilder()
.title("增强开源测试")
.description("测试增强API是否可用")
.termsOfServiceUrl("")
.version("2.7.0-1-beta4")
.build())
.directModelSubstitute(Byte.class, Integer.class)
.select()
.apis(RequestHandlerSelectors.basePackage("cn.weiguangfu.swagger2.plus.demo.controller"))
.paths(PathSelectors.any())
.build();
}
}
Controller接口配置
- @ApiPlus 接口增强注解 默认不增强
- @ApiGroup 接口方法注解 默认不增强
- groups 区分接口的分组Class类标记
- requestExecution 请求执行方式(包含: 默认参数中全部不展示, 排除: 默认参数全部展示),默认包含
- responseExecution 响应执行方式(包含: 默认参数中全部不展示, 排除: 默认参数全部展示),默认包含
/**
* @ApiPlus配置并且设置value=true表示开启当前Controller的API增强
*/
@RestController
@RequestMapping(value = "/swagger2/plus")
@ApiPlus(value = true)
@Api("swagger2plus测试类")
public class Swagger2PlusController {
/**
* @ApiGroup设置请求与响应的参数分组, 注解参数如下
* 1. groups: 进行分组区别的Class对象.
* 2. requestExecution: 请求执行方式 参见{@link cn.weiguangfu.swagger2.plus.enums.ApiExecutionEnum}
* 3. responseExecution: 响应执行方式 参见{@link cn.weiguangfu.swagger2.plus.enums.ApiExecutionEnum}
*/
@PostMapping("/demo")
@ApiOperation("swagger2plus测试方法")
@ApiGroup(groups = Swagger2PlusGroups.Demo.class, responseExecution = ApiExecutionEnum.EXCLUDE)
public Swagger2Plus demo(@RequestBody Swagger2Plus swagger2Plus) {
return swagger2Plus;
}
}
请求与响应参数对象配置
- @ApiRequestInclude 请求包含配置, @ApiGroup中requestExecution配置为包含(ApiExecutionEnum.INCLUDE)时, 此注解生效
- @ApiRequestExclude 请求排除配置, @ApiGroup中requestExecution配置为排除(ApiExecutionEnum.EXCLUDE)时, 此注解生效
- @ApiResponseInclude 响应包含配置, @ApiGroup中responseExecution配置为包含(ApiExecutionEnum.INCLUDE)时, 此注解生效
- @ApiResponseExclude 响应排除配置, @ApiGroup中responseExecution配置为排除(ApiExecutionEnum.EXCLUDE)时, 此注解生效
- @ApiRequestFieldRequired 请求字段必填注解, 使用@ApiGroup修饰的接口(分组的接口)下, 使用此注解可以表示指定分组使用请求字段是否必填. 注: 此字段会忽略@ApiModelProperty的required属性, 优先@ApiRequestFieldRequired确定字段是否必填.
@ApiModel("Swagger2增强对象")
public class Swagger2Plus {
@ApiModelProperty("名称")
@ApiRequestInclude(groups = {Swagger2PlusGroups.Demo.class})
@ApiResponseExclude(groups = {Swagger2PlusGroups.Demo.class})
@ApiRequestFieldRequired(groups = {Swagger2PlusGroups.Demo.class})
private String name;
@ApiModelProperty("版本")
@ApiRequestInclude(groups = {Swagger2PlusGroups.Demo.class})
@ApiResponseExclude(groups = {Swagger2PlusGroups.Demo.class})
private String version;
@ApiModelProperty("子Swagger2增强对象")
private Swagger2Plus swagger2Plus;
...
}
具体效果图如下
结束语
2.7.0-1版本的目前开始添加字段是否必填的功能, 目前测试中, 等稳定后其他版本也会陆续上线.
由于目前2.7.0-1-bate4我们在进行使用中,其他版本目前只有简单测试,由于是耦合性非常低,大家可以放心接入自己的项目,如果有任何问题或者意见与建议,欢迎大家来github给我留言或者发送邮件weiguangfu520@163.com。