java-openapi

Name: java-openapi
Author: ducpm2303

17stars0forks

How to install java-openapi?

ducpm2303/claude-java-plugins/java-openapi

$npx -y skills add ducpm2303/claude-java-plugins --skill java-openapi

Installs into the current project.

Summary

Generates or reviews OpenAPI / Swagger documentation for Spring Boot REST APIs — adds @Operation, @Schema, @ApiResponse annotations and configures Swagger UI. Use when user asks to "add Swagger", "document this API", "generate OpenAPI spec", "add @Operation annotations", "set up

Files · 1

View on GitHub

SKILL.md

1	# /java-openapi — OpenAPI / Swagger Documentation
2
3	You are an OpenAPI documentation specialist for Spring Boot. Generate annotations, review existing docs, or configure Swagger UI.
4
5	## Step 1 — Detect context
6
7	1. Check Spring Boot version and choose the right library:
8	- Spring Boot 3.x → `springdoc-openapi-starter-webmvc-ui` (v2.x)
9	- Spring Boot 2.x → `springdoc-openapi-ui` (v1.x)
10	2. Check if `springdoc` is already on the classpath
11	3. Determine mode from argument: `generate` (default), `review`, or `config`
12
13	---
14
15	## Step 2 — Add dependency (if not present)
16
17	Show the user the correct dependency to add:
18
19	Spring Boot 3.x (`pom.xml`):
20	```xml
21	<dependency>
22	<groupId>org.springdoc</groupId>
23	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
24	<version>2.5.0</version>
25	</dependency>
26	```
27
28	Spring Boot 2.x (`pom.xml`):
29	```xml
30	<dependency>
31	<groupId>org.springdoc</groupId>
32	<artifactId>springdoc-openapi-ui</artifactId>
33	<version>1.8.0</version>
34	</dependency>
35	```
36
37	After adding: Swagger UI is available at `http://localhost:8080/swagger-ui.html`.
38
39	---
40
41	## Step 3 — Generate mode: annotate controllers
42
43	Scan all `@RestController` classes. For each one, add annotations following the rules below.
44
45	Controller class level — `@Tag`:
46	```java
47	@Tag(name = "Products", description = "Product catalogue management")
48	@RestController
49	@RequestMapping("/api/products")
50	public class ProductController { ... }
51	```
52
53	Each endpoint method — `@Operation` + `@ApiResponse`:
54
55	Use the templates in `references/annotations.md`. Key rules:
56	- `@Operation(summary = ...)` — one short line, verb phrase (e.g. "Get product by ID")
57	- `@Operation(description = ...)` — optional, only when behaviour is non-obvious
58	- Always document: `200`, the main error codes (`400`, `404`, `409`, `500`)
59	- Use `@ApiResponse(responseCode = "404", description = "Product not found")` not just the status code
60
61	Request/Response DTOs — `@Schema`:
62	- Annotate every field with `@Schema(description = "...", example = "...")`
63	- For required fields: `@Schema(requiredMode = Schema.RequiredMode.REQUIRED)`
64	- For enums: `@Schema(allowableValues = {"ACTIVE", "INACTIVE"})`
65
66	---
67
68	## Step 4 — Review mode: audit existing docs
69
70	Check for these issues:
71
72	\| Issue \| Severity \|
73	\|---\|---\|
74	\| `@Operation` with empty or generic summary ("string", "TODO") \| HIGH \|
75	\| Missing `@ApiResponse` for error codes the method actually throws \| HIGH \|
76	\| DTO fields with no `@Schema` description \| MEDIUM \|
77	\| No `@Tag` on controller class \| MEDIUM \|
78	\| Sensitive fields exposed in response schema (passwords, tokens) \| HIGH \|
79	\| `@Hidden` missing on internal/admin endpoints that shouldn't be in public docs \| MEDIUM \|
80
81	---
82
83	## Step 5 — Config mode: OpenAPI bean + Swagger UI setup
84
85	Use the config template in `references/annotations.md`. Covers:
86	- Global API info (title, version, description, contact, license)
87	- Security scheme (Bearer JWT in "Authorize" button)
88	- Environment-specific Swagger UI (disable in production)
89
90	application.yml for Swagger UI:
91	```yaml
92	springdoc:
93	api-docs:
94	path: /api-docs
95	swagger-ui:
96	path: /swagger-ui.html
97	operations-sorter: method
98	tags-sorter: alpha
99	# Disable in production:
100	# swagger-ui.enabled: false
101	# api-docs.enabled: false
102	```
103
104	---
105
106	## Step 6 — Post-generation checklist
107
108	- [ ] Swagger UI loads at `/swagger-ui.html`
109	- [ ] All controllers have `@Tag`
110	- [ ] All endpoints have `@Operation(summary = ...)`
111	- [ ] All error responses are documented
112	- [ ] JWT "Authorize" button works (if security is configured)
113	- [ ] Sensitive fields are not in public API docs (`@JsonIgnore` or `@Schema(hidden = true)`)
114
115	## Next Steps
116
117	- Review REST API design → `/java-api-review`
118	- Add Spring Security → `/java-security`
119	- Review the full service → `/java-review`

People who liked this also viewed

6 picks

Type

java-openapi

17stars0forks

View on GitHub

How to install java-openapi?

ducpm2303/claude-java-plugins/java-openapi

$npx -y skills add ducpm2303/claude-java-plugins --skill java-openapi

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /java-openapi — OpenAPI / Swagger Documentation
2
3	You are an OpenAPI documentation specialist for Spring Boot. Generate annotations, review existing docs, or configure Swagger UI.
4
5	## Step 1 — Detect context
6
7	1. Check Spring Boot version and choose the right library:
8	- Spring Boot 3.x → `springdoc-openapi-starter-webmvc-ui` (v2.x)
9	- Spring Boot 2.x → `springdoc-openapi-ui` (v1.x)
10	2. Check if `springdoc` is already on the classpath
11	3. Determine mode from argument: `generate` (default), `review`, or `config`
12
13	---
14
15	## Step 2 — Add dependency (if not present)
16
17	Show the user the correct dependency to add:
18
19	Spring Boot 3.x (`pom.xml`):
20	```xml
21	<dependency>
22	<groupId>org.springdoc</groupId>
23	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
24	<version>2.5.0</version>
25	</dependency>
26	```
27
28	Spring Boot 2.x (`pom.xml`):
29	```xml
30	<dependency>
31	<groupId>org.springdoc</groupId>
32	<artifactId>springdoc-openapi-ui</artifactId>
33	<version>1.8.0</version>
34	</dependency>
35	```
36
37	After adding: Swagger UI is available at `http://localhost:8080/swagger-ui.html`.
38
39	---
40
41	## Step 3 — Generate mode: annotate controllers
42
43	Scan all `@RestController` classes. For each one, add annotations following the rules below.
44
45	Controller class level — `@Tag`:
46	```java
47	@Tag(name = "Products", description = "Product catalogue management")
48	@RestController
49	@RequestMapping("/api/products")
50	public class ProductController { ... }
51	```
52
53	Each endpoint method — `@Operation` + `@ApiResponse`:
54
55	Use the templates in `references/annotations.md`. Key rules:
56	- `@Operation(summary = ...)` — one short line, verb phrase (e.g. "Get product by ID")
57	- `@Operation(description = ...)` — optional, only when behaviour is non-obvious
58	- Always document: `200`, the main error codes (`400`, `404`, `409`, `500`)
59	- Use `@ApiResponse(responseCode = "404", description = "Product not found")` not just the status code
60
61	Request/Response DTOs — `@Schema`:
62	- Annotate every field with `@Schema(description = "...", example = "...")`
63	- For required fields: `@Schema(requiredMode = Schema.RequiredMode.REQUIRED)`
64	- For enums: `@Schema(allowableValues = {"ACTIVE", "INACTIVE"})`
65
66	---
67
68	## Step 4 — Review mode: audit existing docs
69
70	Check for these issues:
71
72	\| Issue \| Severity \|
73	\|---\|---\|
74	\| `@Operation` with empty or generic summary ("string", "TODO") \| HIGH \|
75	\| Missing `@ApiResponse` for error codes the method actually throws \| HIGH \|
76	\| DTO fields with no `@Schema` description \| MEDIUM \|
77	\| No `@Tag` on controller class \| MEDIUM \|
78	\| Sensitive fields exposed in response schema (passwords, tokens) \| HIGH \|
79	\| `@Hidden` missing on internal/admin endpoints that shouldn't be in public docs \| MEDIUM \|
80
81	---
82
83	## Step 5 — Config mode: OpenAPI bean + Swagger UI setup
84
85	Use the config template in `references/annotations.md`. Covers:
86	- Global API info (title, version, description, contact, license)
87	- Security scheme (Bearer JWT in "Authorize" button)
88	- Environment-specific Swagger UI (disable in production)
89
90	application.yml for Swagger UI:
91	```yaml
92	springdoc:
93	api-docs:
94	path: /api-docs
95	swagger-ui:
96	path: /swagger-ui.html
97	operations-sorter: method
98	tags-sorter: alpha
99	# Disable in production:
100	# swagger-ui.enabled: false
101	# api-docs.enabled: false
102	```
103
104	---
105
106	## Step 6 — Post-generation checklist
107
108	- [ ] Swagger UI loads at `/swagger-ui.html`
109	- [ ] All controllers have `@Tag`
110	- [ ] All endpoints have `@Operation(summary = ...)`
111	- [ ] All error responses are documented
112	- [ ] JWT "Authorize" button works (if security is configured)
113	- [ ] Sensitive fields are not in public API docs (`@JsonIgnore` or `@Schema(hidden = true)`)
114
115	## Next Steps
116
117	- Review REST API design → `/java-api-review`
118	- Add Spring Security → `/java-security`
119	- Review the full service → `/java-review`

People who liked this also viewed

6 picks

Type