Introduction

When Springfox stops working after a Spring Boot upgrade, the failure is usually not "Swagger is broken" in the abstract. It is usually a dependency alignment problem, an autoconfiguration mismatch, or an outdated integration approach that no longer fits the Spring Boot version in the project.

What Usually Fails on Spring Boot 2.2

With Spring Boot 2.2.x, the common symptoms are:

• '/swagger-ui.html returns 404'
• '/v2/api-docs is empty or errors'
• the Docket bean exists but no controllers are discovered
• dependency conflicts produce startup errors

Older guides often mix springfox-swagger2, springfox-swagger-ui, and hand-written configuration copied from earlier Spring Boot versions. That combination can work, but it is sensitive to dependency drift.

Start with a Clean Dependency Set

If you are staying on Springfox, keep the dependency setup minimal and consistent. A common working approach is the Springfox Boot starter:

1<dependency>
2    <groupId>io.springfox</groupId>
3    <artifactId>springfox-boot-starter</artifactId>
4    <version>3.0.0</version>
5</dependency>

Then add one explicit configuration class:

1@Configuration
2public class SwaggerConfig {
3
4    @Bean
5    public Docket api() {
6        return new Docket(DocumentationType.OAS_30)
7            .select()
8            .apis(RequestHandlerSelectors.basePackage("com.example.api"))
9            .paths(PathSelectors.any())
10            .build();
11    }
12}

This is easier to reason about than mixing older Springfox modules with custom UI wiring.

Check Controller Discovery

If the UI loads but shows no endpoints, the issue is often package scanning. The Docket above only scans com.example.api. If your controllers live under com.example.web, they will not appear.

A quick example controller:

1@RestController
2@RequestMapping("/greetings")
3public class GreetingController {
4
5    @GetMapping
6    public String hello() {
7        return "hello";
8    }
9}

After startup, verify:

curl http://localhost:8080/v2/api-docs

If this endpoint fails, fix that first. The UI depends on the generated docs endpoint.

Common Causes Beyond Dependencies

Security configuration can block the Swagger endpoints. If Spring Security is active, permit the documentation paths explicitly:

1@Override
2protected void configure(HttpSecurity http) throws Exception {
3    http.authorizeRequests()
4        .antMatchers(
5            "/swagger-ui/**",
6            "/swagger-ui.html",
7            "/v2/api-docs",
8            "/swagger-resources/**",
9            "/webjars/**"
10        ).permitAll()
11        .anyRequest().authenticated();
12}

Another cause is path customization. If the app runs behind a servlet context path or reverse proxy, the generated URLs may not match what the UI expects.

You should also avoid mixing incompatible transitive versions of Jackson, Spring MVC, or plugin libraries through unmanaged overrides in the build file.

When to Stop Fixing Springfox

Even if you can make Springfox work on Spring Boot 2.2, it is worth asking whether you should keep investing in it. Springfox has seen far less active maintenance than newer OpenAPI integrations.

For teams planning further upgrades, moving to springdoc-openapi is often the more stable direction. That is especially true if the codebase will later move to newer Spring Boot lines.

Still, if the immediate task is to get an existing 2.2 application unstuck, the shortest path is usually:

• align Springfox dependencies
• reduce configuration complexity
• verify controller scanning
• permit Swagger endpoints through security

Common Pitfalls

The biggest mistake is copying fragments from multiple tutorials into one project. Old dependency sets, new annotations, and custom security rules easily conflict.

Another common issue is debugging the UI before debugging /v2/api-docs. If the docs endpoint is broken, the UI problem is only a symptom.

Developers also forget package boundaries. A perfectly valid Docket can still document nothing if it scans the wrong base package.

Finally, treat Springfox as legacy infrastructure. If you need long-term compatibility, solving today’s 2.2 issue is not the same thing as choosing the best future tool.

Summary

• Springfox issues on Spring Boot 2.2 are usually dependency or configuration mismatches.
• Start with a clean Springfox dependency setup and a minimal Docket bean.
• Verify /v2/api-docs before investigating the UI.
• Make sure controller package scanning and security rules include the Swagger endpoints.
• Consider springdoc-openapi if the project needs a better-maintained path forward.