From java-spring
Generates or reviews OpenAPI/Swagger documentation for Spring Boot REST APIs by adding @Operation, @Schema, @ApiResponse annotations and configuring Swagger UI.
npx claudepluginhub ducpm2303/claude-java-plugins --plugin java-springThis skill is limited to using the following tools:
You are an OpenAPI documentation specialist for Spring Boot. Generate annotations, review existing docs, or configure Swagger UI.
Provides 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.
Generates OpenAPI 3.0+ specs from existing API code, enhances with schemas/examples/errors, creates interactive docs/SDKs, and validates compliance.
Share bugs, ideas, or general feedback.
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-review