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>
1
2
3
4
5

其他项目管理工具(Gradle Groovy等)对接入口

配置文件开启Swagger2增强

此配置为了适应配置文件方式的profile, 可以配置停用线上swagger2的增强

# 此配置标志着开启增强, 目的是为了可以屏蔽线上Swagger2增强.
# 不编辑此配置或者值为enable: false则不开启Swagger2增强.
swagger:
  plus:
    enable: true
1
2
3
4
5

开启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();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

请求与响应参数对象配置

• @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;
    
    ...
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

具体效果图如下

结束语

2.7.0-1版本的目前开始添加字段是否必填的功能, 目前测试中, 等稳定后其他版本也会陆续上线.

由于目前2.7.0-1-bate4我们在进行使用中，其他版本目前只有简单测试，由于是耦合性非常低，大家可以放心接入自己的项目，如果有任何问题或者意见与建议，欢迎大家来github给我留言或者发送邮件weiguangfu520@163.com。