本文介绍如何通过自定义 OpenAPI 规范过滤器，从 Swagger 生成的 API 文档中移除 JAX-RS 资源类中声明但对外不可见的路径前缀（例如 /publicApi），确保文档路径与真实公网访问路径一致。
本文介绍如何通过自定义 openapi 规范过滤器，从 swagger 生成的 api 文档中移除 jax-rs 资源类中声明但对外不可见的路径前缀（例如 `/publicapi`），确保文档路径与真实公网访问路径一致。
在使用 swagger-jaxrs2（v2.2.7+）为基于 JAX-RS 的服务生成 OpenAPI 文档时，若 API 实际通过反向代理或网关暴露在独立域名下（如 https://api.example.com/foo），而内部实现依赖路径前缀（如 @Path("/publicApi")）进行路由隔离，则该前缀会直接透出到生成的 OpenAPI 文档中——导致 /publicApi/foo 出现在 paths 字段，与客户端实际调用路径不符。
这不仅造成文档失真，还可能误导前端开发者或自动化工具，因此需在文档生成阶段主动剥离该内部前缀。
✅ 解决方案：实现 AbstractSpecFilter 进行路径重写
Swagger v3 提供了 AbstractSpecFilter 扩展机制，允许在 OpenAPI 文档最终序列化前对 OpenAPI 对象进行修改。我们可借此遍历所有 paths 键（即路径字符串），将匹配内部前缀的路径截断，仅保留对外可见部分。
以下是一个完整、可直接集成的过滤器示例：
package com.example;
import io.swagger.v3.core.filter.AbstractSpecFilter;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.PathItem;
import io.swagger.v3.oas.models.Paths;
import java.util.Map;
import java.util.Optional;
public class PathSpecFilter extends AbstractSpecFilter {
// 替换为你实际使用的内部前缀，注意末尾不要加斜杠（如 "/publicApi"）
private static final String INTERNAL_PREFIX = "/publicApi";
@Override
public Optional<OpenAPI> filterOpenAPI(
final OpenAPI openAPI,
final Map<String, java.util.List<String>> params,
final Map<String, String> cookies,
final Map<String, java.util.List<String>> headers) {
return super.filterOpenAPI(openAPI, params, cookies, headers)
.map(api -> {
api.setPaths(fixPaths(api.getPaths()));
return api;
});
}
private Paths fixPaths(final Paths paths) {
if (paths == null) return new Paths();
final Paths fixed = new Paths();
for (Map.Entry<String, PathItem> entry : paths.entrySet()) {
String originalPath = entry.getKey();
String cleanedPath = originalPath.startsWith(INTERNAL_PREFIX)
? originalPath.substring(INTERNAL_PREFIX.length())
: originalPath;
// 确保清理后路径不为空且以 '/' 开头（符合 OpenAPI 规范）
if (!cleanedPath.isEmpty() && !cleanedPath.startsWith("/")) {
cleanedPath = "/" + cleanedPath;
}
fixed.put(cleanedPath, entry.getValue());
}
return fixed;
}
}? 配置方式（以 Jersey + swagger-jaxrs2 为例）
在初始化 Swagger 配置时，注册该过滤器：
BeanConfig config = new BeanConfig();
config.setResourcePackage("com.example.api"); // 扫描包
config.setVersion("1.0.0");
config.setTitle("Public API");
config.setScan(true);
// 注册自定义过滤器
config.setFilterClass(PathSpecFilter.class.getName());⚠️ 注意事项：
- INTERNAL_PREFIX 必须与 @Path 中声明的前缀完全一致（包括大小写和斜杠）；
- 若存在嵌套前缀（如 /v1/publicApi），请确保 INTERNAL_PREFIX 精确匹配最外层前缀；
- 该过滤器作用于整个 OpenAPI 文档的 paths 层级，不影响 servers、components 或操作级 summary/description；
- 建议配合 @OpenAPIDefinition(servers = @Server(url = "https://api.example.com")) 显式声明基础 URL，避免因路径变更导致 Base URL 解析歧义。
✅ 效果验证
配置生效后，原生成的：
paths:
/publicApi/foo:
get: { ... }
/publicApi/bar/{id}:
get: { ... }将自动转换为：
paths:
/foo:
get: { ... }
/bar/{id}:
get: { ... }文档路径与真实请求路径完全一致，提升可读性、兼容性和自动化集成可靠性。
此方法无需修改 JAX-RS 注解或引入额外代理层，轻量、可控、符合 OpenAPI 规范演进方向，是生产环境中处理“内部路由前缀透出”问题的标准实践。
