SpringDoc OpenAPI 过滤框架自动生成接口的实践指南

背景与需求场景

在现代Java Web开发中，许多安全框架（如SaToken）会在运行时自动生成一系列REST端点（如/login、/logout等）。这些端点虽然对系统运行至关重要，但通常不应出现在对外暴露的API文档中。开发者期望在生成OpenAPI规范时，能够智能地区分"业务接口"和"框架接口"。

核心解决方案

SpringDoc OpenAPI提供了多种灵活的过滤机制，开发者可以通过以下方式实现接口筛选：

1. 基于包路径的过滤

通过配置springdoc.packagesToScan属性，可以精确控制扫描范围。例如在application.properties中：

springdoc.packages-to-scan=com.example.controller

这种方式适合项目结构规范的情况，能有效排除第三方库中的控制器。

2. 基于URL路径的过滤

使用路径匹配模式进行排除：

springdoc.paths-to-exclude=/auth/**, /internal/**

支持Ant风格的路径模式，特别适合SaToken这类路径规则明确的框架。

3. 注解驱动的过滤

对于更复杂的场景，可以实现MethodFilter接口进行编程式控制：

@Bean
public MethodFilter customFilter() {
    return method -> !method.isAnnotationPresent(FrameworkEndpoint.class);
}

这种方式可以与自定义注解配合，实现更精细的过滤逻辑。

进阶实践技巧

1. 多条件组合过滤：可以同时使用路径排除和包扫描，形成双重过滤机制
2. 环境感知配置：通过Profile区分不同环境的过滤策略
3. 动态过滤：利用SpringDoc的Hook机制，在运行时动态修改API文档

注意事项

1. 过滤规则会影响Swagger UI和OpenAPI JSON/YAML输出
2. 过于宽松的过滤可能导致敏感接口泄露
3. 建议在测试环境验证过滤效果后再部署到生产环境

通过合理运用这些过滤机制，开发者可以生成干净、专业的API文档，既保证框架功能的正常运行，又不会向API消费者暴露不必要的技术细节。