Master SpringDoc: Auto‑Generate OpenAPI Docs in Spring Boot with Zero Configuration

What is SpringDoc

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

Relation to 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 natively.

Why choose SpringDoc

Before SpringDoc, SpringFox was used to integrate Swagger with Spring. SpringFox stopped maintenance and cannot adapt to Spring Boot 2.6+ or 3.x, leading to compatibility issues. SpringDoc fully supports Spring Boot 2.6+ and 3.x, uses JSR‑303 annotations (@Schema, @Parameter) instead of Swagger‑specific ones, reducing learning cost.

Getting Started

Minimal configuration

Step 1: Add dependency

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

Step 2: (Optional) application.yml

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: Configuration class

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

After these steps the documentation is accessible at http://localhost:8080/swagger-ui/index.html. If no controllers exist the page will be empty.

Adding annotations to controllers

Without annotations:

@RestController
@RequestMapping("/main")
public class MainController {
    @GetMapping("/index")
    public String index(String str1) {
        return "请求成功";
    }
}

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 "请求成功";
    }
}

Grouping configuration

Programmatic grouping (high flexibility):

@Configuration
@OpenAPIDefinition(info = @Info(...))
public class SpringDocConfig {
    @Bean
    public GroupedOpenApi userGroup() {
        return GroupedOpenApi.builder()
                .group("商品模块")
                .pathsToMatch("/api/product/**")
                .build();
    }

    @Bean
    public GroupedOpenApi productGroup() {
        return GroupedOpenApi.builder()
                .group("用户模块")
                .packagesToScan("com.ren.main.controller.member")
                .build();
    }
}

Declarative grouping via application.yml:

springdoc:
  group-configs:
    - group: '默认分组'
      paths-to-match: '/**'
    - group: '商品模块'
      paths-to-match: '/api/product/**'
    - group: '用户模块'
      packages-to-scan: 'com.ren.main.controller.member'

When multiple groups match the same endpoint, the endpoint appears in each group.

Handling custom WebMvcConfigurer

If a project overrides addResourceHandlers, the default static resource mappings for Swagger UI are lost. Adding a resource handler restores access:

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

Conclusion

This article outlined the steps to integrate SpringDoc into a Spring Boot project, covering minimal setup, annotation usage, grouping strategies, and adjustments required when customizing WebMvcConfigurer or using Spring Security.