giuseppe-trisciuoglio/spring-boot-openapi-documentation

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

| Concept | Description | |---------|-------------| | Dependencies | springdoc-openapi-starter-webmvc-ui for WebMvc, springdoc-openapi-starter-webflux-ui for WebFlux | | Configuration | application.yml with springdoc.api-docs.* and springdoc.swagger-ui.* properties | | Access Points | OpenAPI JSON: /v3/api-docs, Swagger UI: /swagger-ui/index.html | | Core Annotations | @Tag, @Operation, @ApiResponse, @Parameter, @Schema, @SecurityRequirement | | Security | Configure security schemes in OpenAPI bean, apply with @SecurityRequirement | | Pagination | Use @ParameterObject with Spring Data Pageable |

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