Spring Boot OpenAPI Documentation with SpringDoc

Overview

SpringDoc OpenAPI automates generation of OpenAPI 3.0 documentation for Spring Boot projects with a Swagger UI web interface for exploring and testing APIs.

When to Use

• •Set up SpringDoc OpenAPI in Spring Boot 3.x projects
• •Generate OpenAPI 3.0 specifications for REST APIs
• •Configure and customize Swagger UI
• •Add detailed API documentation with annotations
• •Document request/response models with validation
• •Implement API security documentation (JWT, OAuth2, Basic Auth)
• •Document pageable and sortable endpoints
• •Add examples and schemas to API endpoints
• •Customize OpenAPI definitions programmatically
• •Support multiple API groups and versions
• •Document error responses and exception handlers
• •Add JSR-303 Bean Validation to API documentation
• •Support Kotlin-based Spring Boot APIs

Quick Reference

Instructions

1. Add Dependencies

Add SpringDoc starter for your application type (WebMvc or WebFlux). See dependency-setup.md for Maven/Gradle configuration.

2. Configure SpringDoc

Set basic configuration in application.yml:

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method

See configuration.md for advanced options.

3. Document Controllers

Use OpenAPI annotations to add descriptive information:

@RestController
@Tag(name = "Book", description = "Book management APIs")
public class BookController {

    @Operation(summary = "Get book by ID")
    @ApiResponse(responseCode = "200", description = "Book found")
    @GetMapping("/{id}")
    public Book findById(@PathVariable Long id) { }
}

See controller-documentation.md for patterns.

4. Document Models

Apply @Schema annotations to DTOs:

@Schema(description = "Book entity")
public class Book {
    @Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(example = "Clean Code", required = true)
    private String title;
}

See model-documentation.md for validation patterns.

5. Configure Security

Set up security schemes in OpenAPI bean:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .components(new Components()
            .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
            )
        );
}

Apply with @SecurityRequirement(name = "bearer-jwt") on controllers. See security-configuration.md.

6. Document Pagination

Use @ParameterObject for Spring Data Pageable:

@GetMapping("/paginated")
public Page<Book> findAll(@ParameterObject Pageable pageable) {
    return repository.findAll(pageable);
}

See pagination-support.md.

7. Test Documentation

Access Swagger UI at /swagger-ui/index.html to verify documentation completeness.

8. Customize for Production

Configure API grouping, versioning, and build plugins. See advanced-configuration.md and build-integration.md.

Best Practices

• •Use descriptive operation summaries: Short (< 120 chars), clear statements
• •Document all response codes: Include success (2xx), client errors (4xx), server errors (5xx)
• •Add examples to request/response bodies: Use @ExampleObject for realistic examples
• •Leverage JSR-303 validation annotations: SpringDoc auto-generates constraints from validation annotations
• •Use @ParameterObject for complex parameters: Especially for Pageable, custom filter objects
• •Group related endpoints with @Tag: Organize API by domain entities or features
• •Document security requirements: Apply @SecurityRequirement where authentication needed
• •Hide internal endpoints appropriately: Use @Hidden or create separate API groups
• •Customize Swagger UI for better UX: Enable filtering, sorting, try-it-out features
• •Version your API documentation: Include version in OpenAPI Info

References

• •dependency-setup.md — Maven/Gradle dependencies and version selection
• •configuration.md — Basic and advanced configuration options
• •controller-documentation.md — Controller and endpoint documentation patterns
• •model-documentation.md — Entity, DTO, and validation documentation
• •security-configuration.md — JWT, OAuth2, Basic Auth, API key configuration
• •pagination-support.md — Pageable, Slice, and custom pagination patterns
• •advanced-configuration.md — API groups, customizers, OpenAPI bean configuration
• •exception-handling.md — Exception documentation and error response schemas
• •build-integration.md — Maven/Gradle plugins and CI/CD integration
• •complete-examples.md — Full controller, entity, and configuration examples
• •annotations-reference.md — Complete annotation reference with attributes
• •springdoc-official.md — Official SpringDoc documentation
• •troubleshooting.md — Common issues and solutions

Constraints and Warnings

• •Do not expose sensitive data in API examples or schema descriptions
• •Keep OpenAPI annotations minimal to avoid cluttering controller code; use global configurations when possible
• •Large API definitions can impact Swagger UI performance; consider grouping APIs by domain
• •Schema generation may not work correctly with complex generic types; use explicit @Schema annotations
• •Avoid circular references in DTOs as they cause infinite recursion in schema generation
• •Security schemes must be properly configured before using @SecurityRequirement annotations
• •Hidden endpoints (@Operation(hidden = true)) are still visible in code and may leak through other documentation tools

Examples

Basic Controller Documentation

@RestController
@Tag(name = "Books", description = "Book management APIs")
@RequestMapping("/api/books")
public class BookController {

    @Operation(
        summary = "Get book by ID",
        description = "Retrieves detailed information about a specific book"
    )
    @ApiResponse(responseCode = "200", description = "Book found")
    @ApiResponse(responseCode = "404", description = "Book not found")
    @GetMapping("/{id}")
    public Book getBook(@PathVariable Long id) {
        return bookService.findById(id);
    }

    @Operation(summary = "Create new book")
    @SecurityRequirement(name = "bearer-jwt")
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Book createBook(@Valid @RequestBody CreateBookRequest request) {
        return bookService.create(request);
    }
}

Documented Model with Validation

@Schema(description = "Book entity")
public class Book {
    @Schema(description = "Unique identifier", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(description = "Book title", example = "Clean Code", required = true)
    @NotBlank
    @Size(min = 1, max = 200)
    private String title;

    @Schema(description = "Author name", example = "Robert C. Martin")
    @NotBlank
    private String author;

    @Schema(description = "Price in USD", example = "29.99", minimum = "0")
    @NotNull
    @DecimalMin("0.0")
    private BigDecimal price;
}

Security Configuration

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("Book API")
            .version("1.0.0")
            .description("REST API for book management"))
        .components(new Components()
            .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT"))
            .addSecuritySchemes("api-key", new SecurityScheme()
                .type(SecurityScheme.Type.APIKEY)
                .in(SecurityScheme.In.HEADER)
                .name("X-API-Key")));
}

Related Skills

• •spring-boot-rest-api-standards — REST API design standards
• •spring-boot-dependency-injection — Dependency injection patterns
• •unit-test-controller-layer — Testing REST controllers
• •spring-boot-actuator — Production monitoring and management

External Resources

• •SpringDoc Official Documentation
• •OpenAPI 3.0 Specification
• •Swagger UI Configuration