spring-boot-openapi-documentation

spring-boot-openapi-documentation provides patterns for generating comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. It solves the problem of keeping API documentation accurate, explorable, and testable by automating OpenAPI 3.0 spec generation and exposing a Swagger UI web interface for browsing and trying endpoints. It applies when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or enriching endpoints with examples and schemas, including Kotlin-based Spring Boot APIs.

The skill walks through a concrete workflow: add the SpringDoc starter dependency (springdoc-openapi-starter-webmvc-ui for WebMvc or springdoc-openapi-starter-webflux-ui for WebFlux); configure application.yml using springdoc.api-docs.* and springdoc.swagger-ui.* properties; and document controllers with annotations such as @Tag, @Operation, @ApiResponse, @Parameter, @Schema, and @SecurityRequirement. Access points are the OpenAPI JSON at /v3/api-docs and Swagger UI at /swagger-ui/index.html. It covers documenting models with @Schema, configuring security schemes (JWT, OAuth2, Basic Auth) in an OpenAPI bean and applying them with @SecurityRequirement, and documenting pagination using @ParameterObject with Spring Data Pageable. It also addresses API grouping, versioning, build plugin integration, and JSR-303 Bean Validation. Extensive reference files cover dependency setup, configuration, controller and model documentation, security, pagination, advanced configuration, exception handling, build integration, complete examples, an annotations reference, and troubleshooting.

It targets Spring Boot 3.x developers and API teams who need standardized, discoverable documentation. Stated constraints and warnings include not exposing sensitive data in examples or schema descriptions, keeping annotations minimal to avoid cluttering controllers, considering API grouping because large definitions can impact Swagger UI performance, using explicit @Schema for complex generic types, avoiding circular references in DTOs to prevent infinite recursion, configuring security schemes before applying @SecurityRequirement, and remembering that hidden endpoints remain visible in code and may leak through other documentation tools.