Java Spring Swagger different API documentations

Viewed 1518

I have a Spring application where I exposed two rest interfaces for usage. One is internally for in-house developers the other one is for customers.

Swagger does generate a nice documentation reachable under /swagger-ui.html.
Under this URL it shows the documentation for both internal and external users.

Here is my Code setup:

import org.springframework.boot.info.BuildProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2UiConfiguration extends WebMvcConfigurerAdapter {

    @Bean(name="restInternalSwaggerApi")
    public Docket internalApi(BuildProperties build) {
        final Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .groupName( "internal" )
            .select()
                .apis( RequestHandlerSelectors.basePackage("com.xyz.web.internal") )
            .build();
        return docket;
    }

    @Bean(name="restPublicSwaggerApi")
    public Docket publicApi(BuildProperties build) {
        final Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .groupName( "public" )
            .select()
                .apis( RequestHandlerSelectors.basePackage("com.xyz.web.public") )
            .build();
        return docket;
    }
}

Now, I want to separate these swagger-ui documentations. So that our internal developers access it like
/documentation/private/swagger-ui.html and
/documentation/public/api-v1.html

Both not seeing each other. How to do that?

I found some hints here, but they really were not constructive for me:

http://sp ingfox.github.io/springfox/docs/current/#q13 and linked resources
Customize endpoints of dockets with springfox Swagger
swagger multiple versions in path
https://github.com/springfox/springfox/issues/963
https://github.com/springfox/springfox/issues/1263#issuecomment-210839308

If someone would yield me to the proper documentation I would also be happy.
Let me know If the question is hard to understand and how to improve it.

for version infos on java's maven:

<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>

<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>

In other words:

I want the different APIs reached by the DropDown-Box to have called by different URLs:

enter image description here

I want this, so I can give a customer a different URL with a different API than to giving another URL to my developer colleagues.

1 Answers
  1. Swagger-ui is a module (one of many jars that swagger ui as a solution consists of) that contains html's and css's, thus if you need one more page (in your case api-v1.html) you need to add one more html.

  2. Here are the sources for swagger-ui based on which I have created a modified springfox.js file (for 2.10.5 version) that allows for showing only one docket that have groupName==prefix of the page(e.g. if you have your docket .groupName("external") it will be shown on the page external-swagger-ui.html

  3. So in order this to work you need to add 2 files total files placement Please note that html file is also modified to use custom springfox.js <script src="springfox.js"> </script> instead of the one that goes with springfox-ui jar.(in my case it is resources root as you can see on screenshot)

  4. Default swagger-ui.html has no interference with this solution.

  5. Working example

Related