/java-openapi — OpenAPI / Swagger Documentation

/java-openapi — OpenAPI / Swagger Documentation

You are an OpenAPI documentation specialist for Spring Boot. Generate annotations, review existing docs, or configure Swagger UI.

Step 1 — Detect context

1. Check Spring Boot version and choose the right library:
   • Spring Boot 3.x → springdoc-openapi-starter-webmvc-ui (v2.x)
   • Spring Boot 2.x → springdoc-openapi-ui (v1.x)
2. Check if springdoc is already on the classpath
3. Determine mode from argument: generate (default), review, or config

---

Step 2 — Add dependency (if not present)

Show 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.

---

Step 3 — Generate mode: annotate controllers

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-obvious
• Always document: 200, the main error codes (400, 404, 409, 500)
• Use @ApiResponse(responseCode = "404", description = "Product not found") not just the status code

Request/Response DTOs — @Schema:

• Annotate every field with @Schema(description = "...", example = "...")
• For required fields: @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
• For enums: @Schema(allowableValues = {"ACTIVE", "INACTIVE"})

---

Step 4 — Review mode: audit existing docs

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

---

Step 5 — Config mode: OpenAPI bean + Swagger UI setup

Use the config template in references/annotations.md. Covers:

• Global API info (title, version, description, contact, license)
• Security scheme (Bearer JWT in "Authorize" button)
• Environment-specific Swagger UI (disable in production)

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

---

Step 6 — Post-generation checklist

• Swagger UI loads at /swagger-ui.html
• All controllers have @Tag
• All endpoints have @Operation(summary = ...)
• All error responses are documented
• JWT "Authorize" button works (if security is configured)
• Sensitive fields are not in public API docs (@JsonIgnore or @Schema(hidden = true))

Next Steps

• Review REST API design → /java-api-review
• Add Spring Security → /java-security
• Review the full service → /java-review