Spring Boot Openapi Documentation
Configure SpringDoc OpenAPI groups, scanners, and operation customizers so your Spring Boot API ships accurate interactive docs.
Overview
spring-boot-openapi-documentation is an agent skill for the Build phase that configures SpringDoc OpenAPI groups and customizers for Spring Boot REST APIs.
Install
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentationWhat is this skill?
- GroupedOpenApi beans split public, admin, and user path prefixes
- Package-based scanning for multi-module controller layouts
- Custom groups filtered with addOpenApiMethodFilter and annotation gates
- Global OperationCustomizer patterns for shared header and security metadata
- Advanced SpringDoc configuration beyond a single default Docket-style setup
- Multiple API group patterns: path-based, package-based, and custom filter groups
Adoption & trust: 1.3k installs on skills.sh; 271 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Spring Boot service exposes dozens of routes but Swagger shows one muddy spec that mixes admin, public, and internal controllers.
Who is it for?
Solo builders on Spring Boot 3.x adding multi-tenant or role-split HTTP APIs with SpringDoc.
Skip if: Non-Spring stacks, pure frontend component libraries, or teams that only need markdown API notes without machine-readable OpenAPI.
When should I use this skill?
Adding or refactoring SpringDoc GroupedOpenApi beans, path matchers, or operation customizers on a Spring Boot service.
What do I get? / Deliverables
You publish grouped, filterable OpenAPI definitions aligned to paths and packages so clients and agents consume the right API surface per audience.
- GroupedOpenApi @Bean definitions
- Package- or path-scoped OpenAPI groups
- Customized operation metadata in generated spec
Recommended Skills
Journey fit
OpenAPI wiring is canonical Build work because it documents the API contract while controllers and DTOs are still taking shape. Docs is the right shelf for SpringDoc beans, grouped APIs, and Swagger UI exposure—not generic backend business logic.
How it compares
SpringDoc configuration skill—not a hosted API portal product or Postman collection generator.
Common Questions / FAQ
Who is spring-boot-openapi-documentation for?
Indie backend developers documenting Spring Boot REST services who want grouped OpenAPI specs without maintaining parallel YAML by hand.
When should I use spring-boot-openapi-documentation?
During Build docs while defining controller packages, before sharing Swagger UI with a frontend cofounder, and when splitting public versus admin routes ahead of Launch distribution.
Is spring-boot-openapi-documentation safe to install?
Check the Security Audits panel on this Prism page; the skill suggests Java configuration only and does not itself grant network access beyond what your agent already has.
SKILL.md
READMESKILL.md - Spring Boot Openapi Documentation
# Advanced SpringDoc Configuration ## Multiple API Groups ### Group by Path ```java import org.springdoc.core.models.GroupedOpenApi; @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("public") .pathsToMatch("/api/public/**") .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("admin") .pathsToMatch("/api/admin/**") .build(); } @Bean public GroupedOpenApi userApi() { return GroupedOpenApi.builder() .group("user") .pathsToMatch("/api/user/**") .build(); } ``` ### Group by Package ```java @Bean public GroupedOpenApi controllerGroup() { return GroupedOpenApi.builder() .group("controllers") .packagesToScan("com.example.controller") .build(); } @Bean public GroupedOpenApi controllerGroup2() { return GroupedOpenApi.builder() .group("vendor-controllers") .packagesToScan("com.vendor.controller") .build(); } ``` ### Group with Custom Configuration ```java @Bean public GroupedOpenApi customGroup() { return GroupedOpenApi.builder() .group("custom") .pathsToMatch("/api/custom/**") .addOpenApiMethodFilter(method -> method.isAnnotationPresent(CustomApi.class)) .build(); } ``` ## Custom Operation Customizer ### Global Operation Customization ```java import org.springdoc.core.customizers.OperationCustomizer; @Bean public OperationCustomizer customizeOperation() { return (operation, handlerMethod) -> { // Add custom extension operation.addExtension("x-custom-field", "custom-value"); // Add tag based on annotation if (handlerMethod.getMethod().isAnnotationPresent(Deprecated.class)) { operation.addTagsItem("deprecated"); } // Customize summary String className = handlerMethod.getBeanType().getSimpleName(); operation.setSummary(className + ": " + operation.getSummary()); return operation; }; } ``` ### Conditional Customization ```java @Bean public OperationCustomizer authOperationCustomizer() { return (operation, handlerMethod) -> { // Add security requirement for methods with @RequireAuth if (handlerMethod.hasMethodAnnotation(RequireAuth.class)) { operation.addSecurityItem(new SecurityRequirement().addList("bearer-jwt")); } return operation; }; } ``` ## Hide Endpoints ### Hide Single Endpoint ```java @Operation(hidden = true) @GetMapping("/internal") public String internalEndpoint() { return "Hidden from docs"; } ``` ### Hide Entire Controller ```java import io.swagger.v3.oas.annotations.Hidden; @Hidden @RestController @RequestMapping("/internal") public class InternalController { // All endpoints hidden from documentation } ``` ### Conditional Hiding ```java @Bean public OperationCustomizer conditionalHiding() { return (operation, handlerMethod) -> { // Hide endpoints based on profile if (isProductionProfile()) { if (handlerMethod.getMethod().getName().contains("Debug")) { operation.setHidden(true); } } return operation; }; } ``` ## Custom OpenAPI Bean ### Complete OpenAPI Configuration ```java import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import io.swagger.v3.oas.models.info.License; import io.swagger.v3.oas.models.servers.Server; @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("Book Management API") .description("Comprehensive API for managing books, authors, and publishers") .version("v1.0.0") .contact(new Contact() .name("API Support") .email("support@example.com") .url("https://example.com/support") )