You need to enable JavaScript to run this app. Springdoc OpenAPI如何通过自定义属性分组API,替代硬编码路径匹配
优惠活动
大模型
产品
解决方案
定价
更多

Springdoc OpenAPI如何通过自定义属性分组API,替代硬编码路径匹配

完全可以基于自定义注解实现API分组,彻底解决硬编码路径的维护问题

SpringDoc原生GroupedOpenApi提供的路径、包、请求头匹配规则,确实不直接支持自定义注解识别接口分组,但借助框架内置的OperationCustomizer扩展点,不需要修改框架源码就可以实现注解式分组,完全匹配核心诉求。

具体实现步骤

  1. 定义自定义分组标识注解
    新建可作用于类、方法上的运行时注解,用来标记接口所属的分组:

    @Target({ElementType.METHOD, ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    public @interface ApiGroup {
        /**
         * 标记接口所属的分组名称
         */
        String value();
    }
    
  2. 改造原有分组配置,替换硬编码路径匹配逻辑
    移除原来配置类里硬编码的PROFILE_ONE_PATHS数组,给每个分组增加自定义的OperationCustomizer规则,基于注解匹配接口归属:

    // profileOne分组配置
    @Bean
    public GroupedOpenApi profileOneApi(OpenApiCustomiser springCloudContractCustomizer) {
        return GroupedOpenApi.builder()
                .group("profileOne")
                .addOperationCustomizer((operation, handlerMethod) -> {
                    // 优先匹配方法上的注解,其次匹配Controller类上的注解
                    ApiGroup methodGroup = handlerMethod.getMethodAnnotation(ApiGroup.class);
                    ApiGroup classGroup = handlerMethod.getBeanType().getAnnotation(ApiGroup.class);
                    ApiGroup group = methodGroup != null ? methodGroup : classGroup;
    
                    // 规则1:接口打了@ApiGroup("profileOne")注解,直接纳入当前分组
                    if (group != null && "profileOne".equals(group.value())) {
                        return operation;
                    }
                    // 规则2:兼容默认的profileOne基础路径接口,不需要额外打注解
                    if (operation.getPaths() != null) {
                        boolean isBasePath = operation.getPaths().keySet().stream()
                                .anyMatch(path -> path.startsWith("/v1/profileOne/"));
                        if (isBasePath) {
                            return operation;
                        }
                    }
                    // 不满足规则的接口,从当前分组排除
                    return null;
                })
                .addOpenApiCustomiser(springCloudContractCustomizer)
                .build();
    }
    
    // profileTwo分组配置,复用相同逻辑即可
    @Bean
    public GroupedOpenApi profileTwoApi(OpenApiCustomiser springCloudContractCustomizer) {
        return GroupedOpenApi.builder()
                .group("profileTwo")
                .addOperationCustomizer((operation, handlerMethod) -> {
                    ApiGroup methodGroup = handlerMethod.getMethodAnnotation(ApiGroup.class);
                    ApiGroup classGroup = handlerMethod.getBeanType().getAnnotation(ApiGroup.class);
                    ApiGroup group = methodGroup != null ? methodGroup : classGroup;
    
                    if (group != null && "profileTwo".equals(group.value())) {
                        return operation;
                    }
                    if (operation.getPaths() != null) {
                        boolean isBasePath = operation.getPaths().keySet().stream()
                                .anyMatch(path -> path.startsWith("/v1/profileTwo/"));
                        if (isBasePath) {
                            return operation;
                        }
                    }
                    return null;
                })
                .addOpenApiCustomiser(springCloudContractCustomizer)
                .build();
    }
    
    // common分组配置,无需手动维护排除规则
    @Bean
    public GroupedOpenApi commonApi() {
        return GroupedOpenApi.builder()
                .group("common")
                .pathsToMatch("/v1/common/**")
                .addOperationCustomizer((operation, handlerMethod) -> {
                    // 只要接口标记了任意分组注解,自动从common分组排除
                    ApiGroup methodGroup = handlerMethod.getMethodAnnotation(ApiGroup.class);
                    ApiGroup classGroup = handlerMethod.getBeanType().getAnnotation(ApiGroup.class);
                    if (methodGroup != null || classGroup != null) {
                        return null;
                    }
                    return operation;
                })
                .build();
    }
    
  3. 日常接口使用规则
    不管接口实际路径是什么,只要需要归入对应分组,直接在Controller类或单个接口方法上打注解即可:

    • 对于散落在非基础路径下的profileOne接口(比如v1/test、v1/hello对应的接口),直接在对应类/方法上标记@ApiGroup("profileOne"),不需要额外修改配置类
    • common路径下的接口只要没有打其他分组的注解,就会自动归入common分组,不需要手动添加排除规则
    • 后续新增其他分组,只需要复用相同的配置逻辑即可,不需要维护硬编码的路径集合

方案优势

  • 彻底消除硬编码的路径数组维护成本,新增接口只需要打对应注解即可完成分组归属
  • common分组的排除逻辑完全自动生效,不需要每次新增profileOne/profileTwo的散路径接口时,手动在common分组配置里加排除规则
  • 注解同时支持类级别和方法级别标记,灵活适配不同粒度的分组需求

内容的提问来源于stack exchange,提问作者Guilherme Bernardi

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.28 20:24:05