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

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();