SpringDoc OpenAPI 如何基于注解动态标记API分组

在实际开发中，我们经常需要根据不同的使用场景对API进行分组展示。SpringDoc OpenAPI提供了强大的API分组功能，通过GroupedOpenApi可以灵活地组织API文档。本文将介绍如何基于方法注解实现API分组，并在文档中动态标记每个API的分组来源。

场景需求分析

假设我们有以下典型需求：

1. 需要生成两套API文档：一套包含所有内部API（内部开发使用），另一套只包含对外公开的API（外部开发者使用）
2. 在内部文档中，需要明确标注哪些API同时对外公开
3. 希望通过注解方式（而非手动添加描述）自动实现上述功能

核心实现方案

1. 定义分组注解

首先定义两个自定义注解，用于标记API方法：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface InternalCluster {}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ExternalProduct {}

2. 配置分组Bean

创建两个GroupedOpenApi Bean，分别对应内部和外部API分组：

@Bean
open fun externalProduct(): GroupedOpenApi {
    val filter = OpenApiMethodFilter { method ->
        method.isAnnotationPresent(ExternalProduct::class.java)
    }
    return buildApi("external", filter)
}

@Bean
open fun internalCluster(): GroupedOpenApi {
    val filter = OpenApiMethodFilter { method ->
        method.isAnnotationPresent(InternalCluster::class.java) ||
        method.isAnnotationPresent(ExternalProduct::class.java)
    }
    return buildApi("internal", filter)
}

3. 动态标记API来源

使用OperationCustomizer在生成文档时动态添加标记：

private fun buildApi(name: String, methodFilter: OpenApiMethodFilter): GroupedOpenApi {
    return GroupedOpenApi.builder()
        .group(name)
        .pathsToMatch("$genericBasePath/**")
        .addOpenApiMethodFilter(methodFilter)
        .addOperationCustomizer { operation, handlerMethod ->
            if (handlerMethod.method.isAnnotationPresent(ExternalProduct::class.java)) {
                operation.description = (operation.description ?: "") + 
                    "\n\n[同时对外公开]"
            } else if (handlerMethod.method.isAnnotationPresent(InternalCluster::class.java)) {
                operation.description = (operation.description ?: "") + 
                    "\n\n[仅内部使用]"
            }
            operation
        }
        .build()
}

技术要点解析

1. OpenApiMethodFilter：用于过滤哪些方法应该包含在当前分组中
2. OperationCustomizer：允许在生成文档时对每个操作进行自定义处理
3. handlerMethod参数：提供了对原始Controller方法的访问，可以检查注解等信息

最佳实践建议

1. 将公共路径匹配规则提取为常量，便于维护
2. 考虑使用枚举或常量定义描述后缀，避免硬编码
3. 对于复杂的标记逻辑，可以提取为独立的OperationCustomizer实现类
4. 考虑添加样式标记（如HTML）使提示更醒目

总结

通过结合GroupedOpenApi的分组功能和OperationCustomizer的自定义能力，我们可以实现基于注解的智能API文档分组和标记。这种方法不仅减少了手动维护文档的工作量，还能确保文档与实际代码保持同步，是管理大型API文档集的理想方案。