springboot swagger3 "Failed to load remote configuration."

Question

Spring Boot 2.6.3 with Springdoc.

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.5</version>
        </dependency>

In applicaton.yaml, when I set the path as /v3/api-docs or remove it, that means use the default path "/v3/api-docs". The Swagger UI page shows up correctly with the APIs http://localhost:8080/swagger-ui/index.html

But I want to overite the path as below

  api-docs.path: /bus/v3/api-docs

then Swagger UI displays the "Failed to load remote configuration" error:

Answer 1

Make sure to add "/v3/api-docs/**" in configure method.
@Configuration
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/swagger-ui/**", "
/v3/api-docs/**");
    }
}

Answer 2

I had the same problem, If you are behind a reverse proxy, the fix was to add the following property in application.yml

server:
  forward-headers-strategy: framework

this is needed due to the following

Swagger relies on internal routing to make requests from the clients perspective. Putting the service behind a reverse-proxy without providing the X-Forwarded headers will result in the user not being able to use the documentation as intended

source -> https://medium.com/swlh/swagger-spring-boot-2-with-a-reverse-proxy-in-docker-8a8795aa3da4

Answer 3

If you are using Spring Security in your app, you must include the URL in the configs. Add the code below please to your project.

@Configuration
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/swagger-ui/**", "/bus/v3/api-docs/**");
    }
}

Answer 4

Perform "Empty cache and hard refresh" in your browser.

Answer 5

I think I have solved the problem (thanks to @Ivan Zaitsev), just wanted to add more clarification to the answer.

I too have changed the api-docs.path property and I had the same problem. When I inspect the requests on swagger UI page, swagger-config request returns 404 since it was still trying to get the config from the old URL.

Even though I have changed api-docs.path property, here is the request URL that tries to retrieve swagger-config. http://localhost:8080/api/v3/api-docs/swagger-config

It turned out to be a problem related to openapi-ui, because I was able to solve it when I cleared the browser cache and cookies. It is better do to the tests with incognito browser since it does not hold any data on the session.

Answer 6

If you are using SpringBoot v3, you must use springdoc-openapi v2:

https://springdoc.org/v2/

With gradle, for example:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

Answer 7

It's old question but when I was looking for answer I came here, so after I make it work with newer version, I decided to share my answer, maybe someone find it useful.

This is my implementation for spring security - 3.1.0 and openApi 2.1.0 with gradle:

implementation "org.springframework.boot:spring-boot-starter-security:3.1.0"
implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0"

@EnableWebSecurity
public class SecurityConfiguration {
    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                .csrf().disable()
                .sessionManagement()
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
                .authorizeHttpRequests()
                .requestMatchers("/swagger-ui/**",
                        "/swagger-resources/*",
                        "/v3/api-docs/**")
                .permitAll()
                .anyRequest()
                .authenticated();
        return http.build();
    }
}

You need to specify paths in requestMatcher like "/bus/v3/api-docs". The best option is to implement it one by one:

• check if "/**" works, then
• check if /bus/** works (in my case matcher with default path "/api" which is set for whole project and whole path looked like this - /api/swagger-ui/** didn't work, but /swagger-ui/** worked)
• then another check if /bus/v3/** work

** - two stars are wildcard.

Even my path for swagger looks like this: api/swagger-ui/index.html#/ I needed to add matcher: v3/api-docs/** to make it work.