Introduction

Spring Boot 3 uses Jakarta namespaces and newer framework internals, so older Swagger integrations often fail after an upgrade. The most stable path is to use the springdoc-openapi starter line built for Boot 3. Once dependencies, endpoint paths, and security rules are aligned, the Swagger UI works reliably in local and deployed environments.

Use a Boot 3 Compatible OpenAPI Library

If a project still uses older tooling, first remove incompatible Swagger dependencies. Then add one springdoc-openapi starter from the 2.x line.

Maven example:

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

Gradle example:

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
}

After adding the dependency, start the app and check:

• OpenAPI JSON: /v3/api-docs
• Swagger UI: /swagger-ui/index.html

If those endpoints return data, the integration baseline is correct.

Minimal Controller and Annotation Example

You do not need heavy configuration to get started. A regular Spring REST controller with OpenAPI annotations is enough.

1package com.example.demo.api;
2
3import io.swagger.v3.oas.annotations.Operation;
4import io.swagger.v3.oas.annotations.tags.Tag;
5import org.springframework.web.bind.annotation.GetMapping;
6import org.springframework.web.bind.annotation.RequestMapping;
7import org.springframework.web.bind.annotation.RestController;
8
9@RestController
10@RequestMapping("/api")
11@Tag(name = "health", description = "Service status endpoints")
12public class HealthController {
13
14    @Operation(summary = "Simple health check")
15    @GetMapping("/health")
16    public String health() {
17        return "ok";
18    }
19}

Run the application and confirm the endpoint appears in Swagger UI under the health tag.

Optional OpenAPI Metadata Configuration

For production-facing APIs, set title, version, and contact metadata so docs stay readable and auditable.

1package com.example.demo.config;
2
3import io.swagger.v3.oas.models.OpenAPI;
4import io.swagger.v3.oas.models.info.Contact;
5import io.swagger.v3.oas.models.info.Info;
6import org.springframework.context.annotation.Bean;
7import org.springframework.context.annotation.Configuration;
8
9@Configuration
10public class OpenApiConfig {
11
12    @Bean
13    public OpenAPI apiInfo() {
14        return new OpenAPI()
15            .info(new Info()
16                .title("Order Service API")
17                .version("v1")
18                .description("Public contract for order operations")
19                .contact(new Contact().name("Platform Team").email("[email protected]")));
20    }
21}

This bean is auto-detected and merged into generated docs.

Security Configuration for Documentation Endpoints

A frequent issue is "Swagger UI not loading" even though dependencies are correct. Usually Spring Security is blocking static UI assets or API docs endpoints.

Allow docs endpoints explicitly in your security chain:

1package com.example.demo.config;
2
3import org.springframework.context.annotation.Bean;
4import org.springframework.context.annotation.Configuration;
5import org.springframework.security.config.annotation.web.builders.HttpSecurity;
6import org.springframework.security.web.SecurityFilterChain;
7
8@Configuration
9public class SecurityConfig {
10
11    @Bean
12    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
13        http
14            .authorizeHttpRequests(auth -> auth
15                .requestMatchers(
16                    "/v3/api-docs/**",
17                    "/swagger-ui/**",
18                    "/swagger-ui.html"
19                ).permitAll()
20                .anyRequest().authenticated()
21            )
22            .csrf(csrf -> csrf.disable());
23
24        return http.build();
25    }
26}

In stricter environments, keep CSRF enabled for business endpoints and tune only doc access rules.

Property-Level Customization

You can customize paths and scanning behavior using application properties.

1springdoc:
2  api-docs:
3    path: /docs/api
4  swagger-ui:
5    path: /docs/ui

After this change:

• JSON endpoint becomes /docs/api
• UI endpoint becomes /docs/ui

This is useful when API gateway routing conventions require specific prefixes.

Common Migration Notes

When upgrading from Spring Boot 2:

• Remove old springfox artifacts.
• Confirm imports use jakarta.* where required by Boot 3.
• Re-test security path matchers because docs endpoints may be blocked after filter-chain refactors.

Most failures are dependency mismatch or security configuration, not OpenAPI annotations themselves.

Common Pitfalls

• Keeping outdated Swagger libraries that are incompatible with Spring Boot 3 internals.
• Expecting Swagger UI to load without allowing docs routes in Spring Security.
• Changing docs paths in properties but still opening the default URL.
• Mixing multiple OpenAPI libraries in one project, causing bean conflicts.
• Forgetting to re-run tests after Jakarta namespace migration.

Summary

• Use a Boot 3 compatible springdoc-openapi starter from the 2.x line.
• Verify /v3/api-docs and /swagger-ui/index.html first before deeper tuning.
• Add minimal annotations on controllers, then enrich metadata with an OpenAPI bean.
• Configure security to permit documentation routes explicitly.
• Treat migration work as dependency cleanup plus security path validation.