openapi-first

Name: openapi-first
Author: rrezartprebreza

174stars33forks

How to install openapi-first?

rrezartprebreza/spring-boot-skills/openapi-first

$npx -y skills add rrezartprebreza/spring-boot-skills --skill openapi-first

Installs into the current project.

Summary

Use when the project follows API-first / OpenAPI-first approach: generating controller interfaces, DTOs, and clients from an OpenAPI spec. Use when you see openapi.yaml, openapi-generator-maven-plugin, or ApiDelegate pattern in the project.

Files · 1

View on GitHub

SKILL.md

1	# OpenAPI-First Development
2
3	## Maven Plugin Setup
4
5	```xml
6	<plugin>
7	<groupId>org.openapitools</groupId>
8	<artifactId>openapi-generator-maven-plugin</artifactId>
9	<version>7.5.0</version>
10	<executions>
11	<execution>
12	<goals><goal>generate</goal></goals>
13	<configuration>
14	<inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
15	<generatorName>spring</generatorName>
16	<apiPackage>com.example.api</apiPackage>
17	<modelPackage>com.example.api.model</modelPackage>
18	<configOptions>
19	<delegatePattern>true</delegatePattern> <!-- implement delegate, not controller -->
20	<interfaceOnly>false</interfaceOnly>
21	<useSpringBoot3>true</useSpringBoot3>
22	<useTags>true</useTags>
23	<dateLibrary>java8</dateLibrary>
24	<serializationLibrary>jackson</serializationLibrary>
25	<openApiNullable>false</openApiNullable>
26	<skipDefaultInterface>true</skipDefaultInterface>
27	</configOptions>
28	<generateSupportingFiles>true</generateSupportingFiles>
29	<output>${project.build.directory}/generated-sources/openapi</output>
30	</configuration>
31	</execution>
32	</executions>
33	</plugin>
34	```
35
36	## OpenAPI Spec Example
37
38	```yaml
39	# src/main/resources/openapi.yaml
40	openapi: 3.0.3
41	info:
42	title: Order Service API
43	version: 1.0.0
44
45	paths:
46	/api/v1/orders:
47	post:
48	tags: [Orders]
49	operationId: createOrder
50	requestBody:
51	required: true
52	content:
53	application/json:
54	schema:
55	$ref: '#/components/schemas/CreateOrderRequest'
56	responses:
57	'201':
58	description: Order created
59	content:
60	application/json:
61	schema:
62	$ref: '#/components/schemas/OrderResponse'
63	'400':
64	$ref: '#/components/responses/ValidationError'
65
66	get:
67	tags: [Orders]
68	operationId: listOrders
69	parameters:
70	- name: page
71	in: query
72	schema: { type: integer, default: 0 }
73	- name: size
74	in: query
75	schema: { type: integer, default: 20 }
76	responses:
77	'200':
78	description: Paginated orders
79	content:
80	application/json:
81	schema:
82	$ref: '#/components/schemas/OrderPage'
83
84	components:
85	schemas:
86	CreateOrderRequest:
87	type: object
88	required: [customerEmail, items]
89	properties:
90	customerEmail:
91	type: string
92	format: email
93	items:
94	type: array
95	minItems: 1
96	items:
97	$ref: '#/components/schemas/OrderItemRequest'
98
99	OrderResponse:
100	type: object
101	properties:
102	id:
103	type: string
104	format: uuid
105	status:
106	type: string
107	enum: [PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELLED]
108	customerEmail:
109	type: string
110	createdAt:
111	type: string
112	format: date-time
113
114	responses:
115	ValidationError:
116	description: Validation failed
117	content:
118	application/json:
119	schema:
120	$ref: '#/components/schemas/ApiError'
121	```
122
123	## Implementing the Delegate
124
125	```java
126	// Generated: OrdersApi interface with delegate
127	// Your implementation — never modify generated files
128
129	@Service
130	@RequiredArgsConstructor
131	public class OrdersApiDelegateImpl implements OrdersApiDelegate {
132
133	private final OrderService orderService;
134
135	@Override
136	public ResponseEntity<OrderResponse> createOrder(CreateOrderRequest request) {
137	Order order = orderService.createOrder(request);
138	return ResponseEntity.status(HttpStatus.CREATED)
139	.body(OrderApiMapper.toResponse(order));
140	}
141
142	@Override
143	public ResponseEntity<OrderPage> listOrders(Integer page, Integer size) {
144	Page<Order> orders = orderService.findAll(PageRequest.of(page, size));
145	return ResponseEntity.ok(OrderApiMapper.toPage(orders));
146	}
147	}
148	```
149
150	## .gitignore — Never Commit Generated Files
151
152	```gitignore
153	target/generated-sources/openapi/
154	```
155
156	## Gotchas
157	- Agent modifies generated controller files — NEVER modify generated code, implement delegate
158	- Agent generates code without `useSpringBoot3=true` — uses old `javax.*` imports
159	- Agent commits generated sources — add to `.gitignore`, generate on build
160	- Agent skips `skipDefaultInterface=true` — generates default methods that hide missing impls
161	- Agent mixes generated models with hand-written models — keep them

People who liked this also viewed

6 picks

Type

openapi-first

174stars33forks

View on GitHub

How to install openapi-first?

rrezartprebreza/spring-boot-skills/openapi-first

$npx -y skills add rrezartprebreza/spring-boot-skills --skill openapi-first

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# OpenAPI-First Development
2
3	## Maven Plugin Setup
4
5	```xml
6	<plugin>
7	<groupId>org.openapitools</groupId>
8	<artifactId>openapi-generator-maven-plugin</artifactId>
9	<version>7.5.0</version>
10	<executions>
11	<execution>
12	<goals><goal>generate</goal></goals>
13	<configuration>
14	<inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
15	<generatorName>spring</generatorName>
16	<apiPackage>com.example.api</apiPackage>
17	<modelPackage>com.example.api.model</modelPackage>
18	<configOptions>
19	<delegatePattern>true</delegatePattern> <!-- implement delegate, not controller -->
20	<interfaceOnly>false</interfaceOnly>
21	<useSpringBoot3>true</useSpringBoot3>
22	<useTags>true</useTags>
23	<dateLibrary>java8</dateLibrary>
24	<serializationLibrary>jackson</serializationLibrary>
25	<openApiNullable>false</openApiNullable>
26	<skipDefaultInterface>true</skipDefaultInterface>
27	</configOptions>
28	<generateSupportingFiles>true</generateSupportingFiles>
29	<output>${project.build.directory}/generated-sources/openapi</output>
30	</configuration>
31	</execution>
32	</executions>
33	</plugin>
34	```
35
36	## OpenAPI Spec Example
37
38	```yaml
39	# src/main/resources/openapi.yaml
40	openapi: 3.0.3
41	info:
42	title: Order Service API
43	version: 1.0.0
44
45	paths:
46	/api/v1/orders:
47	post:
48	tags: [Orders]
49	operationId: createOrder
50	requestBody:
51	required: true
52	content:
53	application/json:
54	schema:
55	$ref: '#/components/schemas/CreateOrderRequest'
56	responses:
57	'201':
58	description: Order created
59	content:
60	application/json:
61	schema:
62	$ref: '#/components/schemas/OrderResponse'
63	'400':
64	$ref: '#/components/responses/ValidationError'
65
66	get:
67	tags: [Orders]
68	operationId: listOrders
69	parameters:
70	- name: page
71	in: query
72	schema: { type: integer, default: 0 }
73	- name: size
74	in: query
75	schema: { type: integer, default: 20 }
76	responses:
77	'200':
78	description: Paginated orders
79	content:
80	application/json:
81	schema:
82	$ref: '#/components/schemas/OrderPage'
83
84	components:
85	schemas:
86	CreateOrderRequest:
87	type: object
88	required: [customerEmail, items]
89	properties:
90	customerEmail:
91	type: string
92	format: email
93	items:
94	type: array
95	minItems: 1
96	items:
97	$ref: '#/components/schemas/OrderItemRequest'
98
99	OrderResponse:
100	type: object
101	properties:
102	id:
103	type: string
104	format: uuid
105	status:
106	type: string
107	enum: [PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELLED]
108	customerEmail:
109	type: string
110	createdAt:
111	type: string
112	format: date-time
113
114	responses:
115	ValidationError:
116	description: Validation failed
117	content:
118	application/json:
119	schema:
120	$ref: '#/components/schemas/ApiError'
121	```
122
123	## Implementing the Delegate
124
125	```java
126	// Generated: OrdersApi interface with delegate
127	// Your implementation — never modify generated files
128
129	@Service
130	@RequiredArgsConstructor
131	public class OrdersApiDelegateImpl implements OrdersApiDelegate {
132
133	private final OrderService orderService;
134
135	@Override
136	public ResponseEntity<OrderResponse> createOrder(CreateOrderRequest request) {
137	Order order = orderService.createOrder(request);
138	return ResponseEntity.status(HttpStatus.CREATED)
139	.body(OrderApiMapper.toResponse(order));
140	}
141
142	@Override
143	public ResponseEntity<OrderPage> listOrders(Integer page, Integer size) {
144	Page<Order> orders = orderService.findAll(PageRequest.of(page, size));
145	return ResponseEntity.ok(OrderApiMapper.toPage(orders));
146	}
147	}
148	```
149
150	## .gitignore — Never Commit Generated Files
151
152	```gitignore
153	target/generated-sources/openapi/
154	```
155
156	## Gotchas
157	- Agent modifies generated controller files — NEVER modify generated code, implement delegate
158	- Agent generates code without `useSpringBoot3=true` — uses old `javax.*` imports
159	- Agent commits generated sources — add to `.gitignore`, generate on build
160	- Agent skips `skipDefaultInterface=true` — generates default methods that hide missing impls
161	- Agent mixes generated models with hand-written models — keep them

People who liked this also viewed

6 picks

Type