如何在多 Servlet 环境下正确生成 Swagger API 文档路径-java教程-PHP中文网

本文解决 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/path1

Swagger 并不会自动将 /path1 补全为 /endpoint_1/path1；相反，若您单独启动一个仅用于 Swagger 的 @ApplicationPath("/swagger") 配置类，它只会扫描自身注册的资源（通常为空），或错误地将所有 @Path 视为相对于 /swagger，导致生成 /swagger/path1 这类无效文档路径。

✅ 正确做法：移除所有 @ApplicationPath，统一使用单一 ResourceConfig（或确保 Swagger 扫描覆盖全部资源），并通过 @Path 显式声明完整业务路径：

阿里云AI平台

阿里云AI平台是一款面向企业和开发者的云端人工智能服务平台。

下载

// 统一入口配置（推荐使用一个 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 可靠性与协作效率的基础保障。