Mastering SpringDoc: Quick Setup and Advanced Grouping in 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 documentation and provides an interactive Swagger UI for developers.

Relationship with Swagger

Swagger introduced the OpenAPI specification and provides tools like Swagger UI for interactive documentation. SpringDoc is not a replacement for Swagger; it implements OpenAPI 3 and integrates Swagger UI out of the box.

Why Choose SpringDoc

Before SpringDoc, SpringFox was used to integrate Swagger in the Spring ecosystem, but it stopped being maintained in 2020 and does not support Spring Boot 2.6+ or 3.x. SpringDoc fully supports these versions, uses JSR‑303 annotations such as @Schema and @Parameter, and often requires no additional configuration.

Minimal Configuration

Minimal configuration usage

Step 1: Add the dependency.

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

Step 2: (Optional) basic application.yml settings – the defaults are usually sufficient.

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

Step 3: Add a configuration class to define basic OpenAPI information.

@Configuration
@OpenAPIDefinition(info = @Info(
    title = "Project API Documentation",
    version = "1.0",
    description = "Spring Boot project API documentation"))
public class SpringDocConfig { }

After these steps, the Swagger UI is reachable at http://localhost:8080/swagger-ui/index.html. If no controllers are present, the UI shows 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 = "Parameter 1", required = true) String str1) {
        return "Request successful";
    }
}

Grouping Configuration

Programmatic grouping (high flexibility):

@Configuration
@OpenAPIDefinition(info = @Info(title = "Project API", version = "1.0", description = "SpringBoot API"))
public class SpringDocConfig {
    @Bean
    public GroupedOpenApi userGroup() {
        return GroupedOpenApi.builder()
                .group("Product Module")
                .pathsToMatch("/api/product/**")
                .build();
    }

    @Bean
    public GroupedOpenApi productGroup() {
        return GroupedOpenApi.builder()
                .group("User Module")
                .packagesToScan("com.ren.main.controller.member")
                .build();
    }
}

Declarative grouping via application.yml:

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'

WebMvcConfigurer Adjustments

If you override addResourceHandlers, you must re‑configure the static resource locations for Swagger UI, for example:

@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, allow unauthenticated access to the Swagger UI and OpenAPI endpoints:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
                .requestMatchers("/swagger-ui/**", "/*/api-docs/**", "/swagger-resources/**", "/webjars/**", "/druid/**").permitAll()
                .anyRequest().authenticated());
        return http.build();
    }
}

Conclusion

This article introduced SpringDoc integration steps for a Spring Boot project, covering minimal setup, controller annotations, grouping, and necessary adjustments for custom resource handling and Spring Security.