Springdoc OpenAPI如何通过自定义属性分组API,替代硬编码路径匹配
完全可以基于自定义注解实现API分组,彻底解决硬编码路径的维护问题
SpringDoc原生GroupedOpenApi提供的路径、包、请求头匹配规则,确实不直接支持自定义注解识别接口分组,但借助框架内置的OperationCustomizer扩展点,不需要修改框架源码就可以实现注解式分组,完全匹配核心诉求。
具体实现步骤
定义自定义分组标识注解
新建可作用于类、方法上的运行时注解,用来标记接口所属的分组:@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface ApiGroup { /** * 标记接口所属的分组名称 */ String value(); }改造原有分组配置,替换硬编码路径匹配逻辑
移除原来配置类里硬编码的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(); }日常接口使用规则
不管接口实际路径是什么,只要需要归入对应分组,直接在Controller类或单个接口方法上打注解即可:- 对于散落在非基础路径下的profileOne接口(比如
v1/test、v1/hello对应的接口),直接在对应类/方法上标记@ApiGroup("profileOne"),不需要额外修改配置类 - common路径下的接口只要没有打其他分组的注解,就会自动归入common分组,不需要手动添加排除规则
- 后续新增其他分组,只需要复用相同的配置逻辑即可,不需要维护硬编码的路径集合
- 对于散落在非基础路径下的profileOne接口(比如
方案优势
- 彻底消除硬编码的路径数组维护成本,新增接口只需要打对应注解即可完成分组归属
- common分组的排除逻辑完全自动生效,不需要每次新增profileOne/profileTwo的散路径接口时,手动在common分组配置里加排除规则
- 注解同时支持类级别和方法级别标记,灵活适配不同粒度的分组需求
内容的提问来源于stack exchange,提问作者Guilherme Bernardi
相关产品推荐
相关产品推荐

