openapi-first
Use when the project follows API-first / OpenAPI-first approach: generating controller interfaces, DTOs, and clients from an OpenAPI spec
Install / Use
npx skills add rrezartprebreza/spring-boot-skills --skill openapi-firstInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of openapi-first
openapi-first scores 87/100 on our quality scale, 2270th of 4,698 Development & Engineering skills we index (top 49%).
Its SKILL.md is 6.3 KB long, split into 7 sections with 4 code examples: a thorough specification that gives an agent plenty to work with.
It has 334 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated 18 days ago, so openapi-first is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-12. Automated pattern scan on 2026-11-12. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
openapi-first compared with similar skills
All 4 of these similar skills score higher than openapi-first; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| openapi-first (this skill)by rrezartprebreza | 87 | 334 | 18d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install openapi-first?
- Run
npx skills add rrezartprebreza/spring-boot-skills --skill openapi-first. The install tabs above show the steps for each supported agent. - Which AI agents does openapi-first work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is openapi-first safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is openapi-first still maintained?
- The repository was last updated 18 days ago, so openapi-first is actively maintained.
Skill content
View source on GitHubname: openapi-first description: > 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.
OpenAPI-First Development
Maven Plugin Setup
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>7.5.0</version>
<executions>
<execution>
<goals><goal>generate</goal></goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
<generatorName>spring</generatorName>
<apiPackage>com.example.api</apiPackage>
<modelPackage>com.example.api.model</modelPackage>
<configOptions>
<delegatePattern>true</delegatePattern> <!-- implement delegate, not controller -->
<interfaceOnly>false</interfaceOnly>
<useSpringBoot3>true</useSpringBoot3>
<useTags>true</useTags>
<dateLibrary>java8</dateLibrary>
<openApiNullable>false</openApiNullable>
<skipDefaultInterface>false</skipDefaultInterface> <!-- must stay false with delegatePattern: the controller instantiates a no-op delegate -->
</configOptions>
<!-- NOT generateSupportingFiles=true: that adds a second @SpringBootApplication main class
(repackage fails: "Unable to find a single main class") and a SpringDocConfiguration -->
<supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>
<modelNameSuffix>Dto</modelNameSuffix> <!-- OrderDto, not Order: no clash with domain types -->
<output>${project.build.directory}/generated-sources/openapi</output>
</configuration>
</execution>
</executions>
</plugin>
OpenAPI Spec Example
# src/main/resources/openapi.yaml
openapi: 3.0.3
info:
title: Order Service API
version: 1.0.0
paths:
/api/v1/orders:
post:
tags: [Orders]
operationId: createOrder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'201':
description: Order created
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
$ref: '#/components/responses/ValidationError'
get:
tags: [Orders]
operationId: listOrders
parameters:
- name: page
in: query
schema: { type: integer, default: 0 }
- name: size
in: query
schema: { type: integer, default: 20 }
responses:
'200':
description: Paginated orders
content:
application/json:
schema:
$ref: '#/components/schemas/OrderPage'
components:
schemas:
CreateOrderRequest:
type: object
required: [customerEmail, items]
properties:
customerEmail:
type: string
format: email
items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/OrderItemRequest'
OrderResponse:
type: object
properties:
id:
type: string
format: uuid
status:
type: string
enum: [PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELLED]
customerEmail:
type: string
createdAt:
type: string
format: date-time
OrderItemRequest:
type: object
required: [productId, quantity]
properties:
productId:
type: string
format: uuid
quantity:
type: integer
minimum: 1
OrderPage:
type: object
properties:
content:
type: array
items:
$ref: '#/components/schemas/OrderResponse'
page:
type: integer
size:
type: integer
totalElements:
type: integer
format: int64
ApiError:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: string
responses:
ValidationError:
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Implementing the Delegate
// Generated: OrdersApi interface with delegate
// Your implementation — never modify generated files
@Service
@RequiredArgsConstructor
public class OrdersApiDelegateImpl implements OrdersApiDelegate {
private final OrderService orderService;
@Override
public ResponseEntity<OrderResponse> createOrder(CreateOrderRequest request) {
Order order = orderService.createOrder(request);
return ResponseEntity.status(HttpStatus.CREATED)
.body(OrderApiMapper.toResponse(order));
}
@Override
public ResponseEntity<OrderPage> listOrders(Integer page, Integer size) {
Page<Order> orders = orderService.findAll(PageRequest.of(page, size));
return ResponseEntity.ok(OrderApiMapper.toPage(orders));
}
}
.gitignore — Never Commit Generated Files
target/generated-sources/openapi/
Gotchas
- Agent modifies generated controller files — NEVER modify generated code, implement delegate
- Agent generates code without
useSpringBoot3=true— uses oldjavax.*imports - Agent commits generated sources — add to
.gitignore, generate on build - Agent sets
skipDefaultInterface=truewithdelegatePattern=true— the generated controller instantiates a no-op delegate, so it stops compiling; keep itfalseand cover every operation with a contract test - Agent sets
generateSupportingFiles=true— generates a second@SpringBootApplicationand SpringDoc config; list onlyApiUtil.javainsupportingFilesToGenerate - Agent mixes generated models with hand-written models — keep them separate
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
