用于 API 版本控制的多个 Swagger 端点答案

【问题标题】：Multiple Swagger endpoints for API versioning用于 API 版本控制的多个 Swagger 端点
【发布时间】：2017-10-10 21:24:17
【问题描述】：

我正在使用以下技术：

Java 7
Tomcat7
JAX-RS（泽西 2）
招摇 2
Spring 4.3.3.RELEASE

我的后端托管各种类型的版本化 REST API。我们有一个 v1 和 v2 REST API 上下文基本路径（/api/v1 和 /api/v2）。我们托管这两个不同 API 版本的方式是通过两个不同的 Jersey 资源配置（两个不同的 servlet）。这一切都在一个 Web 应用程序中作为 WAR 文件部署到我们的 Web 应用程序服务器（我们使用 Tomcat7）。

我们所做的基本示例：

@ApplicationPath("/api/v2")
@Configuration
public class RestApiV2JerseyConfig extends ResourceConfig {

    public RestApiV2JerseyConfig() {
        ...
        register(ApiListingResource.class);
        register(SwaggerSerializers.class);
    }

    @Bean
    public void swaggerV2Bean() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setBasePath("/api/v2/);
        beanConfig.setResourcePackage("com.example.rest.v2");
        beanConfig.setScan(true);
        return beanConfig;
    }

}

@ApplicationPath("/api/v1")
@Configuration
public class RestApiV1JerseyConfig extends ResourceConfig {

    public RestApiV1JerseyConfig() {
        ... 
        register(ApiListingResource.class);
        register(SwaggerSerializers.class);
    }

    @Bean
    public void swaggerV1Bean() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setBasePath("/api/v1/);
        beanConfig.setResourcePackage("com.example.rest.v1");
        beanConfig.setScan(true);
        return beanConfig;
    }


}

每个 REST API 都在上述各种配置中相应地注册。

现在，我希望能够为每个这些 servlet 托管 Swagger。这是不可能的，对吗？当我尝试这样做时，Swagger 配置会相互覆盖，每个端点都会返回相同的东西。意思是，https://ip-address/api/v1/swagger.json 和 https://ip-address/api/v2/swagger.json 返回完全相同的响应（v1 或 v2 JSON，取决于哪个先注册）。

所以看起来正在发生的是端点可以成功地为每个 servlet 托管，但是托管的内容不能每个 servlet 都是唯一的。或者，我可能只是把一些小事搞砸了，还没有注意到。

各种东西的版本：

swagger-jersey2-jaxrs 1.5.2-M2
球衣 2.23.1

我在这里缺少什么？这很容易用我提供的代码 sn-ps 重现。有其他人能够成功地做我想做的事吗？

【问题讨论】：

您的问题解决了吗？

标签： java rest swagger jersey-2.0 swagger-2.0

【解决方案1】：

是的，你可以这样做，但是你需要使用 web.xml servlet config 方法（至少，我还没有想出另一种方法）。

BeanConfig 更改：

在 RestApiV1JerseyConfig 中

beanConfig.setConfigId("v1");  
beanConfig.setContextId("v1");
beanConfig.setScannerId("v1");

在 RestApiV2JerseyConfig 中

beanConfig.setConfigId("v2");  
beanConfig.setContextId("v2");
beanConfig.setScannerId("v2");

web.xml（每个 servlet 一个）：

<!-- v1 -->
<init-param>
    <param-name>swagger.scanner.id</param-name>
    <param-value>v1</param-value>
</init-param>
<init-param>
    <param-name>swagger.config.id</param-name>
    <param-value>v1</param-value>
</init-param>
<init-param>
    <param-name>swagger.use.path.based.config</param-name>
    <param-value>v1</param-value>
</init-param>

<!-- v2 -->
<init-param>
    <param-name>swagger.scanner.id</param-name>
    <param-value>v2</param-value>
</init-param>
<init-param>
    <param-name>swagger.config.id</param-name>
    <param-value>v2</param-value>
</init-param>
<init-param>
    <param-name>swagger.use.path.based.config</param-name>
    <param-value>v2</param-value>
</init-param>

【讨论】：