Introduction

A 404 on Swagger UI after upgrading or configuring Spring Boot usually means endpoint path, dependency compatibility, or MVC resource mapping issues. With Spring Boot 2.x and later transitions, common breakages come from outdated springfox versions or missing static resource handlers. The fix is to align Swagger tooling with your Spring version and verify the exact UI path that your dependency exposes.

Core Sections

Check dependency compatibility first

Old springfox builds often break on newer Spring Boot versions.

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

If using springfox, verify version matrix carefully.

Verify Swagger UI endpoint path

Depending on library, UI path differs.

Common paths:

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

curl -I http://localhost:8080/swagger-ui/index.html
curl -I http://localhost:8080/v3/api-docs

Security configuration

Security filters can block Swagger routes and produce 404/401 confusion.

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

Ensure route patterns match actual endpoints.

Context path and reverse proxy

If app runs under custom context path, Swagger URL changes.

server.servlet.context-path=/api

Then UI may be at /api/swagger-ui/index.html.

Resource handler conflicts

Custom MVC config can override static resource mapping. Validate no custom handler disables swagger static assets.

Common Pitfalls

• Using Swagger library version incompatible with Spring Boot version.
• Opening outdated UI URL path after dependency changes.
• Blocking swagger endpoints via security config.
• Ignoring custom context path or reverse-proxy prefixes.
• Overriding MVC resource handlers and breaking static swagger assets.

Implementation Playbook

To make this topic production-ready, treat implementation as a repeatable workflow instead of a one-time fix. Start by defining an explicit baseline with known inputs, expected outputs, and measured runtime behavior. Baselines are critical because many regressions appear only after dependency upgrades, environment changes, or infrastructure shifts that do not modify application code directly. A baseline lets you detect drift quickly and determine whether a failure came from logic changes, runtime configuration, or platform behavior.

Next, design a small but representative validation matrix that covers happy-path, edge-case, and failure-path scenarios. Keep the matrix lightweight enough to run frequently, ideally in local development and CI, and strict enough to catch common integration mistakes. If this topic depends on external services, include deterministic stubs or contract fixtures so tests remain stable and actionable. For observability, log key identifiers, decision branches, and outcome statuses in a structured format; this allows fast correlation in dashboards and incident timelines without manual guesswork.

After correctness checks, add operational safeguards. Define timeout behavior, retry policy, and rollback triggers before rollout. Avoid making multiple high-risk changes simultaneously; apply one change, verify, then continue. Incremental rollout minimizes blast radius and produces clearer diagnostics when behavior diverges from expectations. In shared systems, publish a short runbook that lists prerequisites, expected metrics, and first-response troubleshooting steps. This documentation prevents repeated rediscovery work and improves handoff quality across teams.

Use the following execution checklist for consistent delivery:

11. Capture baseline behavior and expected outputs
22. Run happy-path, edge-case, and failure-path tests
33. Validate environment and dependency compatibility
44. Record structured logs and key performance metrics
55. Roll out incrementally with clear rollback criteria
66. Update runbook notes with observed outcomes

Change Control Note

Apply updates in small increments and verify each increment with one deterministic test run before proceeding. Incremental changes reduce rollback scope and make root-cause analysis faster if behavior shifts after dependency or configuration changes.

Summary

Swagger 404 issues in Spring Boot are typically compatibility or routing problems. Align dependencies, verify correct UI path, and ensure security/resource mappings permit documentation routes. A small endpoint checklist resolves most failures quickly.