spring boot 项目集成 knife4j 2.0.5 并实现入参分组校验显示

之前写过一篇：前后端分离时如何优雅的编写 API 文档

不过其中的部分配置还不够完善，本次对其进行一定的优化。

1 路径分组配置

项目中，有的路径需要登录，有的不需要登录，需要登录的接口还可能需要配置全局 header，用于传输校验使用的 token 等

这里是使用路径进行是否需要登录的匹配，其中，路径包含/pub，则不需要登录，否则，需要登录，同时扫描多个路径，路径之前用英文逗号（,）隔开即可

具体实现如下：

@Autowired
    private SwaggerProperties properties;
	
	@Bean(value = "defaultApi")
    public Docket defaultApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .groupName(properties.getGroupName() + "-待认证")
                .select()
                .apis(getPredicate())
                .paths(PathSelectors.regex("^((?!pub).)*$"))
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    @Bean(value = "pubApi")
    public Docket pubApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .groupName(properties.getGroupName() + "-无认证")
                .select()
                .apis(getPredicate())
                .paths(PathSelectors.regex("^.*pub.*$"))
                .build();
    }
    
    //拼接多路径扫描以实现多包扫描支持
    private Predicate getPredicate() {
        String[] split = properties.getBasePackage().split(",");
        Predicate predicate = null;
        for (String s : split) {
            Predicate secPredicate = RequestHandlerSelectors.basePackage(s);
            predicate = predicate == null ? secPredicate : Predicates.or(secPredicate, predicate);
        }
        return predicate;
    }

    private List<ApiKey> securitySchemes() {
        return newArrayList(
                new ApiKey(properties.getHeader(), properties.getHeader(), "header"));
    }

    private List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^((?!pub).)*$"))
                        .build()
        );
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
                new SecurityReference(properties.getHeader(), authorizationScopes));
    }

SwaggerProperties 配置文件只是把变化的配置放到了配置文件中进行配置

这样，访问 http://{IP}:{port}/doc.html 地址，即可看到效果

2 访问控制

knife 提供了简单的 basic 认证，其中

登录访问：SecurityBasicAuthFilter、生产环境屏蔽：ProductionSecurityFilter

由于项目自定义了部分配置，为了统一，自己实现注入时机

@Bean
    @ConditionalOnMissingBean(SecurityBasicAuthFilter.class)
    @ConditionalOnProperty(name = "swagger.certifiable", havingValue = "true")
    public SecurityBasicAuthFilter securityBasicAuthFilter(SwaggerProperties properties) {
        return new SecurityBasicAuthFilter(properties.getCertifiable(), properties.getUsername(), properties.getPassword());
    }

    @Bean
    @ConditionalOnMissingBean(ProductionSecurityFilter.class)
    @ConditionalOnProperty(name = "swagger.prod", havingValue = "true")
    public ProductionSecurityFilter productionSecurityFilter(SwaggerProperties properties) {
        return new ProductionSecurityFilter(properties.getProd());
    }

这样，在 SwaggerProperties 中配置相应的信息，即可实现相关功能

3 入参分组

在开发的时候，会遇到这样一个情况：

一个 VO 对象在新增的时候某些字段为必填，在更新的时候又非必填。比如用户新增和编辑功能，新增时 id 不是必填，编辑时是必须的，其他的字段如用户名等都是一样新增、编辑都为必填。

而在 swagger 中，不属于新增接口的 id 字段，就不应该显示到文档上，避免前端集成接口不知如何传参的问题

以前是新增、编辑使用不同的实体，或者编辑继承新增实体，再加上 id 字段，但是这样会造成项目中有很多的实体，类臃肿

基于此需求，可以借助 javax.validation.groups 分组功能以及 @Validated 来实现，同时扩展 swagger 的功能，此处参考：https://blog.csdn.net/jianzhang11/article/details/119632467

3.1 自定义分组

import javax.validation.groups.Default;

public interface ValidGroup extends Default {
    interface Create extends ValidGroup {
    }

    interface Update extends ValidGroup {
    }

    interface Query extends ValidGroup {
    }

    interface Delete extends ValidGroup {
    }
}

3.2 使用

controller 层入参上添加分组信息，如：

新增：ValidGroup.Create.class

public RestResult<String> insertUser(@RequestBody @Validated(ValidGroup.Create.class) UserBO user) {
    return usersService.insertUser(user);
}

编辑：ValidGroup.Update.class

public RestResult<String> updateUser(@RequestBody @Validated(ValidGroup.Update.class) UserBO user) {
    return usersService.updateUser(user);
}

入参实体中：

public class UserBO implements Serializable {
    private static final long serialVersionUID = 5699245096095831445L;

    @ApiModelProperty(value = "ID")
    @Null(groups = ValidGroup.Create.class)
    @NotNull(groups = ValidGroup.Update.class, message = "ID不可为空")
    private Long id;
}

这样，再访问新增、编辑接口，即可看到效果。