Spring Boot OpenAPI 3 & Swagger: API Documentation That Stays Accurate (2026)

API documentation that doesn't match the actual API is worse than no documentation. It misleads consumers, breaks integrations, and creates support tickets. SpringDoc OpenAPI generates documentation directly from your Spring Boot code — it can't drift because it's derived from the same annotations that drive your actual endpoints.

---

Setup

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

With zero configuration, this exposes:

• /swagger-ui.html — interactive UI
• /v3/api-docs — raw OpenAPI JSON
• /v3/api-docs.yaml — OpenAPI YAML

---

Documenting Endpoints

@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Orders", description = "Order management endpoints")
@RequiredArgsConstructor
public class OrderController {

    @Operation(
        summary = "Get order by ID",
        description = "Returns a single order with all line items. Requires authentication."
    )
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Order found",
            content = @Content(schema = @Schema(implementation = OrderDto.class))),
        @ApiResponse(responseCode = "404", description = "Order not found",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
        @ApiResponse(responseCode = "403", description = "Access denied")
    })
    @GetMapping("/{id}")
    public ResponseEntity<OrderDto> getOrder(
            @Parameter(description = "Order ID", example = "42", required = true)
            @PathVariable Long id) {
        return ResponseEntity.ok(orderService.findById(id));
    }

    @Operation(summary = "Create a new order")
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public OrderDto createOrder(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                description = "Order creation request",
                required = true
            )
            @RequestBody @Valid CreateOrderRequest request) {
        return orderService.create(request);
    }
}

---

Schema Annotations on DTOs

@Schema(description = "Order creation request")
public record CreateOrderRequest(

    @Schema(description = "Customer ID", example = "123", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull Long customerId,

    @Schema(description = "List of order items", minItems = 1)
    @NotEmpty List<OrderItemRequest> items,

    @Schema(description = "ISO 4217 currency code", example = "USD", defaultValue = "USD")
    @Pattern(regexp = "[A-Z]{3}") String currency
) {}

@Schema(description = "Order item")
public record OrderItemRequest(
    @Schema(description = "Product ID", example = "456") @NotNull Long productId,
    @Schema(description = "Quantity", minimum = "1", maximum = "100") @Min(1) @Max(100) int quantity
) {}

---

Security Scheme: JWT Bearer

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("JOptimize API")
                .description("Java performance monitoring and analysis API")
                .version("v1.0")
                .contact(new Contact()
                    .name("JOptimize Team")
                    .url("https://joptimize.io")
                    .email("support@joptimize.io"))
                .license(new License()
                    .name("MIT")
                    .url("https://opensource.org/licenses/MIT")))
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
            .components(new Components()
                .addSecuritySchemes("bearerAuth",
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")
                        .description("JWT token obtained from /api/v1/auth/login")));
    }
}

With this, the Swagger UI shows an Authorize button where users enter their JWT token — all subsequent requests include it automatically.

---

API Versioning in OpenAPI

// Group by version — separate docs for v1 and v2
@Configuration
public class OpenApiGroupsConfig {

    @Bean
    public GroupedOpenApi v1Api() {
        return GroupedOpenApi.builder()
            .group("v1")
            .pathsToMatch("/api/v1/**")
            .build();
    }

    @Bean
    public GroupedOpenApi v2Api() {
        return GroupedOpenApi.builder()
            .group("v2")
            .pathsToMatch("/api/v2/**")
            .build();
    }
}

Dropdowns in Swagger UI let users switch between /v3/api-docs/v1 and /v3/api-docs/v2.

---

Excluding Endpoints from Docs

// Exclude specific endpoints
@Hidden  // On controller or method
@GetMapping("/internal/debug")
public DebugInfo debug() { ... }

# application.properties — exclude actuator from API docs
springdoc.paths-to-exclude=/actuator/**
springdoc.show-actuator=false

# Only show in non-production profiles
springdoc.swagger-ui.enabled=${SWAGGER_ENABLED:false}

Security tip: disable Swagger UI in production (SWAGGER_ENABLED=false in prod env vars) — it exposes your full API surface.

---

Custom Examples and Enum Docs

@Schema(description = "Order status")
public enum OrderStatus {
    @Schema(description = "Order received, awaiting payment")
    PENDING,
    @Schema(description = "Payment confirmed")
    PAID,
    @Schema(description = "Order picked and shipped")
    SHIPPED,
    @Schema(description = "Order delivered to customer")
    DELIVERED,
    @Schema(description = "Order cancelled by customer or system")
    CANCELLED
}

This renders enum values with descriptions in the Swagger UI — instead of just ["PENDING", "PAID", "SHIPPED"], users see what each value means.

---

Common Mistakes to Avoid

• Enabling Swagger in production — exposes your complete API map; disable with a profile-specific property or env variable
• Not documenting error responses — an endpoint that returns 400, 401, 403, 404 with no @ApiResponse for those codes leaves consumers guessing the error schema
• Using raw Map<String, Object> as request/response types — generates useless {} schema; always use typed DTOs
• Skipping @Parameter on path variables — without it, the Swagger UI shows a plain text box with no type or example

---

Summary

SpringDoc OpenAPI generates accurate, interactive API documentation directly from your Spring Boot code. Configure security schemes for JWT bearer auth, group endpoints by API version, add examples to DTOs with @Schema, and disable the UI in production. The investment in annotation coverage pays off every time a frontend developer or API consumer doesn't need to ask "what does this endpoint return on a 404?".

---

Detect API Documentation Gaps

JOptimize flags undocumented endpoints, missing error response declarations, and raw Map types in REST controllers that produce useless OpenAPI schemas.

• IntelliJ Plugin — API documentation coverage analysis: Install JOptimize for IntelliJ
• Web Dashboard — full API quality audit: Analyze your project free →

Generate API docs that never go stale — free scan.