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

Question

I am working with the following technologies:

• Java 7
• Tomcat7
• JAX-RS (Jersey 2)
• Swagger 2
• Spring 4.3.3.RELEASE

Where my backend hosts various types of versioned REST APIs. We have a v1 and v2 REST API context base path (/api/v1 and /api/v2). The way that we host these two different API versions is via two different Jersey resource configurations (two different servlets). This all in one web application deployed to our web application server (we use Tomcat7) as a WAR file.

Basic example of what we do:

@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;
    }


}

Each REST API is registered accordingly in the various configurations above.

Now, what I want to be able to do is host Swagger for each of these servlets. This is not possible, am I right? When I tried to do this, the Swagger configurations would overwrite each other, and each endpoint would return the same thing. Meaning, https://ip-address/api/v1/swagger.json , and https://ip-address/api/v2/swagger.json return the EXACT same response (either the v1 or v2 JSON, depending on which was registered first).

So what it seems is happening is that the endpoint can be successfully hosted for each servlet, but the content of what is hosted cannot be unique per servlet. Or, I might've just messed something up small and haven't noticed yet.

Version of various things:

• swagger-jersey2-jaxrs 1.5.2-M2
• jersey 2.23.1

What am I missing here? This is fairly easy to reproduce with the code snippets I provided. Has anyone else been able to successfully do what I am trying to do?

Answer 1

Yes, you can do this, but you need to use the web.xml servlet config method (at least, I haven't figured out how to do it another way).

BeanConfig changes:

in RestApiV1JerseyConfig

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

in RestApiV2JerseyConfig

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

web.xml (one for each 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>