Introduction

When Springfox Swagger-UI does not load, the issue is usually configuration compatibility rather than missing UI files. The exact fix depends on your Spring Boot version and endpoint path setup. This guide covers a reliable diagnostic flow and working configurations for common setups.

Verify Version Compatibility First

Springfox has known compatibility limits with newer Spring Boot releases. Before changing code, confirm the version matrix in your project.

A practical rule of thumb:

• Spring Boot 2.x can often run with Springfox 3.0.0 plus configuration tweaks.
• Spring Boot 3.x projects generally work better with springdoc-openapi.

If you are on Boot 3 and starting fresh, migration to springdoc usually saves time.

Minimal Springfox Configuration Example

For a Boot 2.x project, start from a minimal Docket bean and confirm docs endpoint health before troubleshooting UI rendering.

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import springfox.documentation.builders.PathSelectors;
4import springfox.documentation.builders.RequestHandlerSelectors;
5import springfox.documentation.spi.DocumentationType;
6import springfox.documentation.spring.web.plugins.Docket;
7import springfox.documentation.swagger2.annotations.EnableSwagger2;
8
9@Configuration
10@EnableSwagger2
11public class SwaggerConfig {
12
13    @Bean
14    public Docket api() {
15        return new Docket(DocumentationType.SWAGGER_2)
16            .select()
17            .apis(RequestHandlerSelectors.basePackage("com.example.api"))
18            .paths(PathSelectors.any())
19            .build();
20    }
21}

After startup, test:

• /v2/api-docs
• /swagger-ui/
• /swagger-ui/index.html

If JSON docs endpoint fails, fix backend config first. UI depends on that endpoint.

Spring Boot 2.6 Path Matching Fix

A frequent issue is Boot 2.6 path matching changes. Add the matching strategy property when using Springfox.

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

Then restart and test docs endpoints again. This single property resolves many broken Swagger-UI setups on 2.6 and nearby versions.

Security and Reverse Proxy Considerations

If API docs endpoints are secured or behind a gateway, Swagger-UI may load but fail to fetch spec JSON.

Checklist:

• Permit access to docs endpoints in Spring Security.
• Ensure reverse proxy forwards correct path prefixes.
• Confirm CORS rules allow the UI origin.

1http
2    .authorizeHttpRequests(auth -> auth
3        .requestMatchers("/v2/api-docs", "/swagger-ui/**", "/swagger-resources/**").permitAll()
4        .anyRequest().authenticated()
5    );

Also inspect browser network logs. A 401, 403, or 404 on docs JSON usually identifies the root cause quickly.

Consider Migration to springdoc-openapi

If you are blocked by compatibility issues, migration can be simpler than patching around framework drift.

1<dependency>
2    <groupId>org.springdoc</groupId>
3    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
4    <version>2.6.0</version>
5</dependency>

With springdoc, UI is typically available at /swagger-ui/index.html, and OpenAPI JSON at /v3/api-docs.

Quick Diagnostic Script

When debugging in a team environment, a repeatable check script saves time. Run these checks after each configuration change.

curl -i http://localhost:8080/v2/api-docs
curl -i http://localhost:8080/swagger-ui/index.html

If docs JSON returns success but UI fails, inspect static resource mapping and proxy path rewriting. If docs JSON fails, focus on Spring config, security chain, and version compatibility first.

Also confirm no conflicting WebMvc configuration overrides default resource handlers. Custom MVC config classes can unintentionally disable Swagger-UI resource resolution.

Common Pitfalls

A common pitfall is checking only the UI page and ignoring whether the API spec endpoint is actually reachable. Another issue is mixing old and new Springfox annotations or dependencies in the same project, causing classpath confusion. Teams also often forget that security filters can block docs endpoints in non-local profiles. Finally, reverse proxy path rewriting can silently break relative links used by Swagger-UI. Validate behavior both directly on the app port and through the full gateway path to isolate where routing fails.

Summary

• Confirm Springfox and Spring Boot version compatibility first.
• Start with a minimal Docket config and test docs JSON endpoint directly.
• Apply path matching configuration for Boot 2.6 style issues.
• Verify security, CORS, and gateway routing for docs endpoints.
• Consider springdoc-openapi for newer Boot versions and simpler maintenance.