Partner – Trifork – NPI (cat=Spring Boot)
announcement - icon

Navigating the complexities of Spring can be difficult, even for seasoned developers.

If you need direct, practical help and guidance with your own Spring work, Trifork's CTO, Joris Kuipers, is running a closed-door call.

It's free, but it's limited to only 3 seats, so if you need it, I would join quickly and be sure to attend:

>>> CTO Spring Open Office Hour Session - Technical Guidance

With more than 15 years of leading custom software development projects involving Spring, Joris has gained a lot of real-world experience, and this call is about sharing and helping the community.

Enjoy.

Course – LS – All

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

>> CHECK OUT THE COURSE

1. Overview

As good developers, we already 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 understand how to change the Swagger-UI URL prefix that is by default provided by these tools.

2. Changing Swagger UI URL Prefix With Springdoc

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

Firstly, as per the above tutorial, we 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.

Let's look at two approaches to customize the swagger-UI URL, let's say to begin with /myproject.

2.1. Using the application.properties File

As we are already familiar with the many different properties in Spring, we 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 do this change by making the following 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 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 have a 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.

Firstly, as per the above-given tutorial, we 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>

Let's say, for instance, 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

Similarly, as in the above example for SpringDoc, adding the following property in the application.properties file will help us in changing 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.html";
    }
}

5. Conclusion

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

As always, the complete code samples for this article can be found over on GitHub.

Course – LS – All

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

>> CHECK OUT THE COURSE
res – REST with Spring (eBook) (everywhere)
Comments are closed on this article!