本文解决 Jersey 多 @ApplicationPath 应用共存时 Swagger 无法识别真实业务路径的问题，核心方案是弃用多个 @ApplicationPath，改用统一根路径 + @Path 显式声明完整资源路径，确保 OpenAPI 文档准确反映实际 HTTP 接口地址。
本文解决 jersey 多 `@applicationpath` 应用共存时 swagger 无法识别真实业务路径的问题，核心方案是弃用多个 `@applicationpath`，改用统一根路径 + `@path` 显式声明完整资源路径，确保 openapi 文档准确反映实际 http 接口地址。
在基于 Jersey 和 Swagger（如 swagger-jaxrs2）构建的微服务或多模块 REST API 项目中，开发者常尝试通过多个 @ApplicationPath（如 /endpoint_1、/endpoint_2）隔离不同功能模块。然而，Swagger 的 OpenAPI 扫描机制仅作用于单个 ResourceConfig 实例的注册上下文，且不感知 @ApplicationPath 的运行时路由前缀——它只解析 @Path 注解声明的相对路径，并默认将其挂载到当前 ResourceConfig 所绑定的 Servlet 上下文根路径下。
因此，当您定义：
@ApplicationPath("/endpoint_1")
public class Endpoint1 extends ResourceConfig { /* ... */ }
@Path("/path1")
public class SomeObject1 { } // 实际访问路径：/endpoint_1/path1Swagger 并不会自动将 /path1 补全为 /endpoint_1/path1；相反，若您单独启动一个仅用于 Swagger 的 @ApplicationPath("/swagger") 配置类，它只会扫描自身注册的资源（通常为空），或错误地将所有 @Path 视为相对于 /swagger，导致生成 /swagger/path1 这类无效文档路径。
✅ 正确做法：移除所有 @ApplicationPath，统一使用单一 ResourceConfig（或确保 Swagger 扫描覆盖全部资源），并通过 @Path 显式声明完整业务路径：
// 统一入口配置（推荐使用一个 ResourceConfig）
@ApplicationPath("/")
public class ApiConfig extends ResourceConfig {
public ApiConfig() {
// 注册全部资源类
register(SomeObject1.class);
register(SomeObject2.class);
// 注册 Swagger OpenAPI 资源
OpenApiResource openApiResource = new OpenApiResource();
SwaggerConfiguration config = new SwaggerConfiguration()
.openAPI(new OpenAPI())
.prettyPrint(true);
openApiResource.setOpenApiConfiguration(config);
register(openApiResource);
}
}
// 资源类中显式写出完整路径
@Path("/endpoint_1/path1")
public class SomeObject1 {
@GET
@Produces(MediaType.TEXT_PLAIN)
public String getEndpoint1() {
return "From endpoint_1";
}
}
@Path("/endpoint_2/path2")
public class SomeObject2 {
@GET
@Produces(MediaType.TEXT_PLAIN)
public String getEndpoint2() {
return "From endpoint_2";
}
}这样，Swagger 扫描到的 @Path 值即为真实可访问路径，生成的 OpenAPI 文档中 paths 字段将准确显示：
paths:
/endpoint_1/path1:
get: { ... }
/endpoint_2/path2:
get: { ... }? 注意事项：
- 若必须物理隔离（如部署为独立 WAR），请改用 Servlet 容器级路径映射（如 Tomcat 的 context.xml 或 Spring Boot 的 server.servlet.context-path），而非 @ApplicationPath；
- 使用 swagger-jaxrs2 时，确保 OpenApiResource 与业务资源注册在同一个 ResourceConfig 实例中；
- 如需动态分组，可在 OpenAPI 对象中通过 addTags() 和 setServers() 手动组织逻辑分组，而非依赖路径前缀。
最终，Swagger UI 将正确展示 http://host:port/endpoint_1/path1 等真实端点，实现文档与运行时行为的一致性——这是 API 可靠性与协作效率的基础保障。
