spring-boot-openapi-documentation_skill

Overview

This skill provides patterns and ready-to-use configurations to generate comprehensive REST API documentation with SpringDoc OpenAPI 3.0 and Swagger UI for Spring Boot 3.x applications. It covers dependency setup, controller and model annotations, security schemes, pagination, grouping, and build-time OpenAPI generation. The guidance helps teams produce accurate, testable API specs and integrate documentation into CI/CD pipelines.

How this skill works

The skill explains which SpringDoc starters to add for WebMvc or WebFlux and shows application.yml/properties settings to expose OpenAPI JSON/YAML and Swagger UI. It describes how to annotate controllers, request bodies, DTOs and exception handlers to populate the OpenAPI spec with schemas, examples, validation rules and response codes. It also demonstrates configuring security schemes (JWT, OAuth2, Basic), API groups, customizers, and build plugins to generate docs during the build.

When to use it

• Setting up OpenAPI documentation for Spring Boot 3.x REST services
• Adding examples, schemas and validation metadata to DTOs
• Documenting authentication and authorization schemes (JWT, OAuth2, Basic)
• Generating API docs for WebMvc or WebFlux applications
• Integrating API spec generation into CI/CD and builds

Best practices

• Use springdoc starters appropriate to your stack (webmvc or webflux) and keep versions up to date
• Annotate controllers and models with Operation, ApiResponse and Schema to ensure accurate types and examples
• Define and reuse common schemas and examples to avoid duplication across endpoints
• Expose only intended endpoints and hide internal controllers or endpoints with @Hidden or Operation(hidden=true)
• Add build plugin execution to generate JSON/YAML artifacts for CI and contract tests

Example use cases

• Expose Swagger UI at /swagger-ui/index.html for developer testing and integration teams
• Document pageable endpoints using @ParameterObject Pageable for accurate query parameter docs
• Add JWT bearer and OAuth2 security schemes and apply @SecurityRequirement on protected controllers
• Create multiple GroupedOpenApi beans to version or separate public and admin API docs
• Generate openapi.json during the build and publish it as a build artifact for contract testing