Master SpringDoc: Zero‑Config API Docs for Spring Boot 2.6+

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.

Relationship with Swagger

Swagger introduced the OpenAPI specification and provides the Swagger UI for interactive documentation. SpringDoc is not a replacement for Swagger; it implements OpenAPI 3 and integrates Swagger UI as the documentation front‑end.

Why Choose SpringDoc

Before SpringDoc, SpringFox was used to integrate Swagger, but it stopped receiving updates and cannot support Spring Boot 2.6+ or 3.x. SpringDoc fully supports these versions, works with JDK 17+, and requires little to no configuration. It uses standard JSR‑303 annotations such as @Schema and @Parameter, reducing the learning curve.

SpringFox Features

Scans @RestController, @RequestMapping, and Swagger‑specific annotations like @ApiOperation to extract paths, parameters, and responses.

Generates OpenAPI 2.0 or 3.0 JSON files.

Provides a Docket configuration class for custom scanning ranges and document metadata.

Swagger UI Features

Renders the JSON generated by SpringFox as an interactive web page (e.g., http://localhost:8080/swagger-ui.html).

Shows endpoint lists, parameter details, request examples, and allows online testing.

Ensures compatibility with other Swagger tools such as Swagger Editor.

Migration to SpringDoc

SpringFox is no longer maintained and cannot adapt to newer Spring Boot versions, leading many projects to adopt SpringDoc, which offers zero‑configuration usage by simply adding one dependency.

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>
</dependency>

Step 2: (Optional) application.yml defaults

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 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 accessible at http://localhost:8080/swagger-ui/index.html. If no controllers exist, the UI shows an empty page.

Grouping Configuration

SpringDoc supports grouping APIs either programmatically or declaratively.

Programmatic (Java Config)

@Configuration
@OpenAPIDefinition(info = @Info(
    title = "Project API Documentation",
    version = "1.0",
    description = "Spring Boot project API docs"
))
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();
    }
}

Beans of type GroupedOpenApi are detected at startup and create separate documentation groups. If multiple groups match the same endpoint, the endpoint appears in each group.

Declarative (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 declarative approach yields the same UI as the programmatic one.

Handling Custom WebMvcConfigurer

If a project overrides addResourceHandlers, the default static‑resource mappings for Swagger UI are lost. Re‑add them manually:

@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());
    }
}

Integrating with Spring Security

When Spring Security is present, static resources for SpringDoc must be permitted. Example configuration:

@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/**", "/v3/api-docs/**", "/swagger-resources/**", "/webjars/**").permitAll()
                .anyRequest().authenticated()
        );
        return http.build();
    }
}

After adding these rules, SpringDoc works correctly alongside Spring Security.

Conclusion

This article demonstrated how to integrate SpringDoc into a Spring Boot project, covering minimal setup, API grouping, and necessary adjustments when customizing WebMvcConfigurer or using Spring Security.