SpringDoc OpenAPI
Auto-generates OpenAPI 3 documentation for Spring Boot applications — replaces SpringFox (which stopped being maintained). SpringDoc scans Spring MVC/WebFlux @RestController annotations, @RequestMapping, @RequestBody, @PathVariable, and response types to generate /v3/api-docs (JSON) and Swagger UI at /swagger-ui.html. Supports Spring Security integration (adds lock icons for secured endpoints), Spring Data REST, Spring Cloud Function, and Kotlin coroutines. OpenAPI annotations (@Operation, @ApiResponse, @Parameter) enrich auto-generated docs. SpringDoc 2.x is for Spring Boot 3.x; SpringDoc 1.x is for Spring Boot 2.x.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Swagger UI and API docs endpoints must be secured in production — they expose agent API surface. Avoid /v3/api-docs on public production endpoints without authentication. Internal developer tools access only. Agent API keys and auth tokens must not appear in Swagger UI examples.
⚡ Reliability
Best When
You have a Spring Boot REST agent API and want auto-generated OpenAPI 3 docs + Swagger UI with minimal configuration — SpringDoc generates documentation directly from your existing Spring annotations.
Avoid When
You're not on Spring Boot, you prefer API-first design (write OpenAPI spec first), or you need documentation for non-REST agent interfaces.
Use Cases
- • Auto-generate OpenAPI 3 docs for agent REST API — SpringDoc scans @RestController and produces /v3/api-docs JSON and Swagger UI at /swagger-ui.html without manual spec writing
- • Document agent API authentication requirements in Swagger UI — Spring Security integration adds padlock icons and security schemes to Swagger UI for JWT and API key secured agent endpoints
- • Generate agent API client SDKs from SpringDoc OpenAPI spec — /v3/api-docs output feeds OpenAPI Generator to produce typed Python, TypeScript, or Go agent API clients
- • Add rich agent endpoint documentation with @Operation annotations — describe agent request/response examples, deprecated endpoints, and error codes in structured OpenAPI format
- • Configure Swagger UI for agent developer portal — customize springdoc.swagger-ui.path, add logo, enable/disable try-it functionality for self-service agent API exploration
Not For
- • Non-Spring Java frameworks — SpringDoc is Spring-specific; use Quarkus SmallRye OpenAPI for Quarkus, or Micronaut OpenAPI for Micronaut agent APIs
- • Manual OpenAPI spec authoring — SpringDoc auto-generates from code; for API-first design where OpenAPI spec is written before code, use direct OpenAPI YAML with OpenAPI Generator
- • Non-REST APIs — SpringDoc documents HTTP REST; use proto-based documentation tools for gRPC agent APIs
Interface
Authentication
Documentation library — no auth for SpringDoc itself. Generated Swagger UI can include agent API auth (JWT bearer, API key) via @SecurityScheme annotations. Secure /v3/api-docs and /swagger-ui.html in production via Spring Security.
Pricing
SpringDoc OpenAPI is Apache 2.0 licensed, community-maintained. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ SpringDoc 2.x vs 1.x compatibility — SpringDoc 2.x is for Spring Boot 3.x (Spring Framework 6); SpringDoc 1.x is for Spring Boot 2.x; using wrong version causes ClassNotFoundException for jakarta.* vs javax.* package names
- ⚠ Swagger UI path conflict with Spring Security — Swagger UI at /swagger-ui.html and /swagger-ui/** must be permitted in Spring Security config; forgetting to permitAll() for these paths returns 401 for Swagger UI in agent API projects
- ⚠ springdoc-openapi-starter-webmvc-ui vs webflux-ui — Spring MVC apps use springdoc-openapi-starter-webmvc-ui; Spring WebFlux uses springdoc-openapi-starter-webflux-ui; adding wrong starter causes NoSuchBeanDefinitionException or missing routes
- ⚠ actuator endpoints pollute API docs — Spring Boot Actuator endpoints appear in Swagger UI by default; filter with springdoc.paths-to-exclude=/actuator/** to exclude internal agent health check endpoints from public API docs
- ⚠ Kotlin data class nullability — SpringDoc respects Kotlin nullable types (String?) and generates 'nullable: true' in OpenAPI spec; ensure Kotlin Jackson module is on classpath for correct serialization of Kotlin agent models in Swagger UI examples
- ⚠ @Schema annotations are for enrichment, not replacement — SpringDoc auto-infers schema from Java/Kotlin types; @Schema should add descriptions and examples, not redefine types; conflicting @Schema types cause incorrect spec generation for agent API models
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for SpringDoc OpenAPI.
Scores are editorial opinions as of 2026-03-06.