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.
res – REST with Spring (eBook) (everywhere)
