Change Swagger-UI URL prefix

1. Overview

As good developers, we know that documentation is essential to building REST APIs, as it helps consumers of the APIs work seamlessly. Most Java developers today are working with Spring Boot. As of today, two tools simplify the generation and maintenance of Swagger API docs using Springfox and SpringDoc.

In this tutorial, we’ll discuss how to change the Swagger-UI URL prefix that’s provided by these tools by default. 

2. Changing Swagger UI URL Prefix With Springdoc

To begin, we can check out how to set up the REST API documentation using OpenAPI 3.0.

First, as per the above article, we’ll need to add an entry to add the dependency for SpringDoc:

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.0.2</version>
</dependency>

The default URL for the swagger-ui will be http://localhost:8080/swagger-ui.html.

Now let’s look at two approaches to customize the swagger-UI URL. We’ll begin with /myproject.

2.1. Using the application.properties File

As we’re already familiar with the many different properties in Spring, we’ll need to add the following properties to the application.properties file:

springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.path=/myproject

2.2. Using Configuration Class

We can also make this change in the configuration file:

@Component
public class SwaggerConfiguration implements ApplicationListener<ApplicationPreparedEvent> {

    @Override
    public void onApplicationEvent(final ApplicationPreparedEvent event) {
        ConfigurableEnvironment environment = event.getApplicationContext().getEnvironment();
        Properties props = new Properties();
        props.put("springdoc.swagger-ui.path", swaggerPath());
        environment.getPropertySources()
          .addFirst(new PropertiesPropertySource("programmatically", props));
    }

    private String swaggerPath() {
        return "/myproject"; // TODO: implement your logic here.
    }
}

In this case, we’ll need to register the listener before the application starts:

public static void main(String[] args) {
    SpringApplication application = new SpringApplication(SampleApplication.class);
    application.addListeners(new SwaggerConfiguration());
    application.run(args);
}

3. Changing Swagger UI URL Prefix With Springfox

We can look at how to set up the REST API documentation by Setting an Example and Description with Swagger and Setting Up Swagger 2 with a Spring REST API Using Springfox.

First, as per the above articles, we’ll need to add an entry to add the dependency for Springfox:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

Now let’s say we want to change this URL to http://localhost:8080/myproject/swagger-ui/index.html. Let’s review two approaches that can help us achieve it.

3.1. Using the application.properties File

Similar to the above example for SpringDoc, adding the following property in the application.properties file will help us change it successfully:

springfox.documentation.swagger-ui.base-url=myproject

3.2. Using Docket Bean in Configuration

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.any())
      .paths(PathSelectors.any())
      .build();
}

@Override
public void addViewControllers(ViewControllerRegistry registry) {
   registry.addRedirectViewController("/myproject", "/");
}

4. Adding a Redirect Controller

We can also add a redirection logic to the API endpoint. In this case, it won’t matter if we use SpringDoc or Springfox:

@Controller
public class SwaggerController {

@RequestMapping("/myproject")
public String getRedirectUrl() {
       return "redirect:swagger-ui/";
    }
}

5. Conclusion

In this article, we learned how to change the default swagger-ui URL for REST API documentation using Springfox and SpringDoc.