From java-spring
Generates or reviews OpenAPI/Swagger documentation for Spring Boot REST APIs by adding @Operation, @Schema, @ApiResponse annotations and configuring Swagger UI.
How this skill is triggered — by the user, by Claude, or both
Slash command
/java-spring:java-openapiThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are an OpenAPI documentation specialist for Spring Boot. Generate annotations, review existing docs, or configure Swagger UI.
You are an OpenAPI documentation specialist for Spring Boot. Generate annotations, review existing docs, or configure Swagger UI.
springdoc-openapi-starter-webmvc-ui (v2.x)springdoc-openapi-ui (v1.x)springdoc is already on the classpathgenerate (default), review, or configShow the user the correct dependency to add:
Spring Boot 3.x (pom.xml):
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.5.0</version>
</dependency>
Spring Boot 2.x (pom.xml):
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.8.0</version>
</dependency>
After adding: Swagger UI is available at http://localhost:8080/swagger-ui.html.
Scan all @RestController classes. For each one, add annotations following the rules below.
Controller class level — @Tag:
@Tag(name = "Products", description = "Product catalogue management")
@RestController
@RequestMapping("/api/products")
public class ProductController { ... }
Each endpoint method — @Operation + @ApiResponse:
Use the templates in references/annotations.md. Key rules:
@Operation(summary = ...) — one short line, verb phrase (e.g. "Get product by ID")@Operation(description = ...) — optional, only when behaviour is non-obvious200, the main error codes (400, 404, 409, 500)@ApiResponse(responseCode = "404", description = "Product not found") not just the status codeRequest/Response DTOs — @Schema:
@Schema(description = "...", example = "...")@Schema(requiredMode = Schema.RequiredMode.REQUIRED)@Schema(allowableValues = {"ACTIVE", "INACTIVE"})Check for these issues:
| Issue | Severity |
|---|---|
@Operation with empty or generic summary ("string", "TODO") | HIGH |
Missing @ApiResponse for error codes the method actually throws | HIGH |
DTO fields with no @Schema description | MEDIUM |
No @Tag on controller class | MEDIUM |
| Sensitive fields exposed in response schema (passwords, tokens) | HIGH |
@Hidden missing on internal/admin endpoints that shouldn't be in public docs | MEDIUM |
Use the config template in references/annotations.md. Covers:
application.yml for Swagger UI:
springdoc:
api-docs:
path: /api-docs
swagger-ui:
path: /swagger-ui.html
operations-sorter: method
tags-sorter: alpha
# Disable in production:
# swagger-ui.enabled: false
# api-docs.enabled: false
/swagger-ui.html@Tag@Operation(summary = ...)@JsonIgnore or @Schema(hidden = true))/java-api-review/java-security/java-reviewnpx claudepluginhub ducpm2303/claude-java-plugins --plugin java-springProvides patterns to generate OpenAPI 3.0 REST API documentation using SpringDoc and Swagger UI in Spring Boot 3.x apps. Use for setup, annotations, security docs, pagination, and examples.
Generates OpenAPI specs and interactive API docs with Swagger/Redoc. Handles spec-first contracts and code-first auto-generation from Express, FastAPI, NestJS, Spring Boot.
OpenAPI/Swagger, schema-driven documentation, examples, and interactive API docs.