Spring Boot: From Basics to Production · Building REST APIs with Spring MVC
API Documentation with springdoc-openapi
Generate OpenAPI docs and Swagger UI from your controllers.
springdoc-openapi scans controllers and generates an OpenAPI 3 document (/v3/api-docs) and Swagger UI (/swagger-ui.html). Enrich it with @Operation, @ApiResponse and schema annotations, group endpoints, document security schemes, and disable or protect the UI in production if the API is private. The spec can generate typed clients for frontends and other services.
@OpenAPIDefinition(info = @Info(title = "Shop API", version = "v1"))
@SecurityScheme(name = "bearer", type = SecuritySchemeType.HTTP, scheme = "bearer", bearerFormat = "JWT")
@Configuration
class OpenApiConfig {}
@Operation(summary = "Get a product", security = @SecurityRequirement(name = "bearer"))
@ApiResponse(responseCode = "404", description = "Product not found",
content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
@GetMapping("/{id}")
ProductResponse get(@PathVariable long id) { /* ... */ }
springdoc:
swagger-ui:
enabled: ${SWAGGER_UI_ENABLED:false}
Common pitfalls
- Publishing internal/admin endpoints in public docs.
- Undocumented error responses.
- Docs drifting from behavior because examples are hand-written.
Key points
- springdoc generates OpenAPI 3
- Document errors and security
- Control exposure per environment
Further reading: springdoc-openapi
Practice questions
Where does springdoc expose the OpenAPI JSON by default?
Answer
At /v3/api-docs, with Swagger UI at /swagger-ui.html (redirecting to /swagger-ui/index.html).
How can a TypeScript frontend use the generated spec?
Answer
Generate types or a client from /v3/api-docs (e.g., with openapi-typescript or openapi-generator) to keep the frontend in sync with the API.
Open in the app to mark lessons complete, take notes and track your progress.