Master SpringDoc: Minimal OpenAPI 3 Setup for Spring Boot

What is SpringDoc

SpringDoc is a library designed for Spring Boot applications that automatically generates API documentation compliant with the OpenAPI 3 specification. It scans controllers, method annotations, and configuration to produce JSON/YAML/HTML docs and provides an interactive Swagger UI for developers.

Relation to Swagger

Swagger introduced the OpenAPI concept and provides the Swagger UI for interactive docs. SpringDoc is not a replacement for Swagger; it implements the OpenAPI 3 standard and natively integrates Swagger UI as the documentation interface.

Why Choose SpringDoc

SpringFox, the previous solution, stopped receiving updates around 2020 and cannot work with Spring Boot 2.6+ or 3.x, causing compatibility issues. SpringDoc fully supports Spring Boot 2.6+ and 3.x (including JDK 17+), requires only a single dependency for zero‑configuration usage, and uses standard JSR‑303 annotations such as @Schema and @Parameter instead of SpringFox‑specific ones.

Minimal Configuration

Step 1: Add the Maven dependency

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- use the latest version -->
</dependency>

Step 2: (Optional) Application.yml defaults

# application.yml
springdoc:
  packages-to-scan: com.example.controller
  swagger-ui:
    enabled: true
    path: /swagger-ui/index.html
    url: /v3/api-docs
  api-docs:
    enabled: true
    path: /api-docs

Step 3: Add a configuration class for basic info

@Configuration
@OpenAPIDefinition(info = @Info(
    title = "Project API Documentation",
    version = "1.0",
    description = "Spring Boot project API docs"
))
public class SpringDocConfig {
    // No additional configuration needed
}

After these steps, the Swagger UI is reachable at http://localhost:8080/swagger-ui/index.html. If the project has no controllers, the UI will show an empty page.

Adding Annotations to Controllers

Without annotations:

@RestController
@RequestMapping("/main")
public class MainController {
    @GetMapping("/index")
    public String index(String str1) {
        return "request successful";
    }
}

With Swagger annotations:

@RestController
@RequestMapping("/main")
@Tag(name = "Demo controller", description = "Demo controller")
public class MainController {
    @GetMapping("/index")
    @Operation(summary = "Demo method", description = "Demo method description")
    public String index(@Parameter(description = "Param 1", required = true) String str1) {
        return "request successful";
    }
}

Now the method details appear in the generated documentation.

Grouped Documentation (Programmatic)

Define beans of type GroupedOpenApi to create separate groups.

@Configuration
@OpenAPIDefinition(info = @Info(
    title = "Project API Documentation",
    version = "1.0",
    description = "Spring Boot project API docs"
))
public class SpringDocConfig {
    /** Product group – path‑based scanning */
    @Bean
    public GroupedOpenApi productGroup() {
        return GroupedOpenApi.builder()
            .group("Product Module")
            .pathsToMatch("/api/product/**")
            .build();
    }

    /** User group – package‑based scanning */
    @Bean
    public GroupedOpenApi userGroup() {
        return GroupedOpenApi.builder()
            .group("User Module")
            .packagesToScan("com.ren.main.controller.member")
            .build();
    }

    /** Default group – shows all APIs */
    @Bean
    public GroupedOpenApi defaultGroup() {
        return GroupedOpenApi.builder()
            .group("Default Group")
            .pathsToMatch("/**")
            .build();
    }
}

SpringDoc discovers these beans at startup, creates the groups, and displays them in the UI. Overlapping paths cause an endpoint to appear in multiple groups.

Declarative Grouping (YAML)

springdoc:
  group-configs:
    - group: 'Default Group'
      paths-to-match: '/**'
    - group: 'Product Module'
      paths-to-match: '/api/product/**'
    - group: 'User Module'
      packages-to-scan: 'com.ren.main.controller.member'

The effect is identical to the programmatic approach but centralizes configuration.

Handling Static Resources with WebMvcConfigurer

If a custom WebMvcConfigurer overrides addResourceHandlers, Spring’s default static‑resource mappings are lost. Add a handler for Swagger UI:

@Configuration
public class ResourcesConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
            .setCacheControl(CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());
    }
}

Spring Security Integration

When Spring Security is present, static Swagger resources must be permitted:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
            .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
            .requestMatchers(request -> {
                String path = request.getServletPath();
                return request.getMethod().equals("GET") && (
                    "/".equals(path) || path.endsWith(".html") ||
                    path.endsWith(".css") || path.endsWith(".js"));
            }).permitAll()
            .requestMatchers(
                "/swagger-ui/**",
                "/v3/api-docs/**",
                "/swagger-resources/**",
                "/webjars/**",
                "/druid/**"
            ).permitAll()
            .anyRequest().authenticated()
        );
        return http.build();
    }
}

With this configuration, the Swagger UI and API docs are accessible without authentication.

Conclusion

The article demonstrated how to integrate SpringDoc into a Spring Boot project, from a minimal setup to advanced grouped documentation, handling static resources, and configuring Spring Security. Feel free to leave comments for any missing details.