How do I configure a custom URL for the springdoc swagger-ui HTML page? - spring

Question

After adding the springdoc-openapi-ui dependency to my Spring project (not Spring Boot) OpenAPI V3 documentation is generated and can be viewed using the default swagger-ui page: localhost:8080/swagger-ui.html. Because the springdoc documentation replaces previous Swagger documentation I want to make it available at the same URL, localhost:8080/docs/index.html. Based on the springdoc documentation I get the impression that can be done by using the springdoc.swagger-ui.path option in the application.properties:
springdoc.swagger-ui.path=/docs/index.html
However, where I would expect to be able to navigate to the API documentation by going to localhost:8080/docs/index.html I get a 404 instead, localhost:8080/swagger-ui.html still works but now redirects to http://localhost:8080/docs/swagger-ui/index.html?configUrl=/restapi/v3/api-docs/swagger-config.
How can I configure my project too make the swagger-ui page available through a custom URL, i.e. localhost:8080/docs/index.html instead of the default localhost:8080/swagger-ui.html?
Edit
After trying some more to get it working and looking through the available information online, such as the springdoc FAQ (mentioned in this answer by H3AR7B3A7) I couldn't get it working. I've decided to go with a different solution which should have the same effect. The springdoc.swagger-ui.path option allows specifying a custom URL but, as I understand it, going to the custom URL redirects a user to the standard localhost:8080/swagger-ui.html page. So the redirect is now configured manually:
#RequestMapping("/docs/index.html")
public void apiDocumentation(HttpServletResponse response) throws IOException {
response.sendRedirect("/swagger-ui.html");
}

Answer 1

I had a similar task for Spring Boot 2.5.6 and springdoc-openapi-webflux-ui 1.5.12. I've found several possible solutions for myself. Maybe it will be helpful for somebody else.
Set springdoc.swagger-ui.path directly
The straightforward way is to set property springdoc.swagger-ui.path=/custom/path. It will work perfectly if you can hardcode swagger path in your application.
Override springdoc.swagger-ui.path property
You can change default swagger-ui path programmatically using ApplicationListener<ApplicationPreparedEvent>. The idea is simple - override springdoc.swagger-ui.path=/custom/path before your Spring Boot application starts.
#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 "/swagger/path"; //todo: implement your logic here.
}
}
In this case, you must register the listener before your application start:
#SpringBootApplication
#OpenAPIDefinition(info = #Info(title = "APIs", version = "0.0.1", description = "APIs v0.0.1"))
public class App {
public static void main(String[] args) {
SpringApplication application = new SpringApplication(App.class);
application.addListeners(new SwaggerConfiguration());
application.run(args);
}
}
Redirect using controller
You can also register your own controller and make a simple redirect (the same as what you suggest, but in my case, I need to use the WebFlux approach):
#RestController
public class SwaggerEndpoint {
#GetMapping("/custom/path")
public Mono<Void> api(ServerHttpResponse response) {
response.setStatusCode(HttpStatus.PERMANENT_REDIRECT);
response.getHeaders().setLocation(URI.create("/swagger-ui.html"));
return response.setComplete();
}
}
The problem with such an approach - your server will still respond if you call it by address "/swagger-ui.html".

Answer 2

Apparantly the library integrates natively only with spring-boot applications like you mentioned in your comment.
If you want to use spring, it's possible but the integration details aren't documented, because it really depends on the version/module and the nature of you spring application.
You can check the FAQ to see if it answers your questions.
There are some more answers here on SO.

Answer 3

I solved by a clear code.
The problem is in webflux that security need permitAll for some uri resources so I solved in this mode in WebFlux Security I image the same in Springboot no WebFlux:
.authorizeExchange().pathMatchers(
// START To show swagger 3:
"/swagger-ui.html",
"/webjars/swagger-ui/**",
"/v3/api-docs/swagger-config",
"/v3/api-docs", // This is the one URI resource used by openApi3 too.
// END To show swagger 3:
"/other-uri-permitAll",
...
"/other-uri-permitAll_N",
.permitAll()
.and()
.authorizeExchange().pathMatchers(
"/other-uri-authenticated-only_1",
"...",
"/other-uri-authenticated-only_1")
.authenticated()
.and()
.authenticationManager(myAuthenticationManager)
.securityContextRepository(mySecurityContextRepository)
.authorizeExchange().anyExchange().authenticated()
.and()
.build();