Openapi

Create a new API spec for an order service

Extend the API in api/orders.yaml with a product endpoint

Generate code from the OpenAPI spec in api/openapi.yaml

Define a REST API for orders and products

Instructions

Before every execution:

1. Check .claude/lessons-learned.md

Step 0 – Detect Mode

The three modes (create, extend, generate code) lead to completely different workflows. Clarify the mode first with AskUserQuestion so no unnecessary work is done.

What would you like to do?

Options:

• Create new spec – Design a new OpenAPI spec from scratch
• Extend existing spec – Add new endpoints or schemas to an existing spec
• Generate code from spec – Generate Java code (DTOs, controllers, services) from an existing spec

Jump to the corresponding steps based on mode:

• Create new spec → Steps A1–A4
• Extend existing spec → Steps B1–B4
• Generate code from spec → Steps 1–4 (existing behavior)

Mode A: Create New Spec

Step A1 – Basics

Ask with AskUserQuestion:

Second question via AskUserQuestion:

What auth scheme should the API use?

Options:

• Bearer JWT (Recommended) – Standard for Keycloak / OAuth2-based systems
• API Key – Simple, for internal services
• OAuth2 – Full OAuth2 flow with scopes
• No authentication – Public API

Step A2 – Data Models

First: Scan existing entities in the project (directories entity/, entity/model/, entity/dto/).

If entities are found, offer via AskUserQuestion (multiSelect):

The following entities were found in the project. Which should be adopted into the API?

Options: list found entity classes (max 4, rest via "Other").

Then: For each new data model, ask interactively:

Repeat the query until the user signals that all models are defined.

Request/Response variants: For each schema, check if separate request and response variants are needed (e.g. CreateOrderRequest without id, OrderResponse with id and timestamps).

Step A3 – Endpoints

Per data model, ask via AskUserQuestion:

What operations should the resource [SchemaName] support?

Options (multiSelect):

• CRUD Set (Recommended) – GET (list + detail), POST, PUT, DELETE
• Read Only – GET (list + detail)
• Create + Read – POST + GET
• Define individually – Specify custom endpoints

For each endpoint, define:

• HTTP method + path (derive from resource: /orders, /orders/{id})
• Request body (reference to schema from A2)
• Response body + status codes (200, 201, 204, 400, 404)
• Query parameters (pagination: page, size, filtering)

Step A4 – Confirmation and Generation

Output compact summary:

API: Order Service (v1.0.0)
Auth: Bearer JWT
Base: /api/v1

Schemas (4):
  CreateOrderRequest, OrderResponse, ProductResponse, ErrorResponse

Endpoints (5):
  GET    /api/v1/orders          → OrderResponse[]
  POST   /api/v1/orders          → OrderResponse
  GET    /api/v1/orders/{id}     → OrderResponse
  GET    /api/v1/products        → ProductResponse[]
  GET    /api/v1/products/{id}   → ProductResponse

File: api/order-service.yaml

Generate?

Only after confirmation generate the YAML file. Template: templates/openapi-spec.yaml.template.

After generation, ask:

Should code be generated directly from the new spec?

If yes → continue with Steps 1–4 (generate code).

Mode B: Extend Existing Spec

Step B1 – Read Spec

Ask for path to existing spec (if not passed as argument). Read and analyze spec:

Existing spec: api/orders.yaml (v1.0.0)

Existing schemas (3):
  CreateOrderRequest, OrderResponse, ErrorResponse

Existing endpoints (3):
  GET    /api/v1/orders
  POST   /api/v1/orders
  GET    /api/v1/orders/{id}

Step B2 – New Data Models

Like Step A2, but additionally show existing schemas as reference. Existing schemas can be used in $ref references of new schemas.

Step B3 – New Endpoints

Like Step A3, but only for new resources or additional operations on existing resources.

Step B4 – Confirmation and Merge

Summary shows only the new elements:

New schemas (2):
  ProductResponse, CreateProductRequest

New endpoints (2):
  GET    /api/v1/products        → ProductResponse[]
  POST   /api/v1/products        → ProductResponse

Existing spec will be extended: api/orders.yaml

Proceed?

Read existing YAML, add new paths and schemas, overwrite file. Existing paths and schemas remain unchanged.

Mode C: Generate Code from Spec

Step 1 – Required Query

Before generation – if not already known:

If the skill is called with arguments (/openapi api/openapi.yaml), $ARGUMENTS is used as the spec path.

Step 2 – Read and Analyze Spec

Read the OpenAPI spec and extract the following:

Step 3 – Output Summary

Before code generation, output a brief overview and get confirmation:

Found endpoints: 5
Found schemas (DTOs): 4
Framework: Quarkus
Package: com.example.orders

Planned files:
  boundary/rest/OrderResource.java      (3 endpoints: GET /orders, POST /orders, GET /orders/{id})
  boundary/rest/ProductResource.java    (2 endpoints: GET /products, GET /products/{id})
  entity/dto/OrderRequest.java          (Record)
  entity/dto/OrderResponse.java         (Record)
  entity/dto/ProductResponse.java       (Record)
  entity/dto/ErrorResponse.java         (Record)

Proceed?

Step 4 – Generate Code

Order: DTOs first, then endpoints, then service stubs.

DTOs (entity/dto/)

• Default: Java Record – immutable, no boilerplate
• Lombok variant only on explicit request
• Field names 1:1 from the spec (camelCase)
• Nullable fields: @Nullable (JSpecify) + Optional<T> only when explicitly needed
• Validation annotations from spec:
  • minLength / maxLength → @Size
  • minimum / maximum → @Min / @Max
  • required → @NotNull / @NotBlank
  • pattern → @Pattern
• Enum values from spec as separate enum types in the same package

Naming convention:

REST Endpoints (boundary/rest/)

Grouping by OpenAPI tag: One tag → one class. No tag → name class after first path segment (/orders/* → OrderResource).

Spring Boot Controller:

@RestController
@RequestMapping("/path")
@Validated
public class {{TAG}}Controller {
    private final {{TAG}}Service {{tag}}Service;
    // Constructor injection
    @GetMapping("/{id}")
    public ResponseEntity<{{ResponseDTO}}> findById(@PathVariable Long id) {
        throw new UnsupportedOperationException("Not implemented yet");
    }
}

Quarkus Resource:

@Path("/path")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class {{TAG}}Resource {
    @Inject
    {{TAG}}Service {{tag}}Service;
    @GET
    @Path("/{id}")
    public {{ResponseDTO}} findById(@PathParam("id") Long id) {
        throw new UnsupportedOperationException("Not implemented yet");
    }
}

Service Stub (control/)

For each controller/resource, a matching empty service stub is created:

@ApplicationScoped  // Quarkus
// @Service          // Spring Boot
public class {{TAG}}Service {
    public {{ResponseDTO}} findById(Long id) {
        throw new UnsupportedOperationException("Not implemented yet");
    }
}

References

Supported OpenAPI Features

Conventions

• Language: English in code and Javadoc comments
• Packages: {{GROUP_ID}}.boundary.rest (endpoints), {{GROUP_ID}}.entity.dto (DTOs), {{GROUP_ID}}.control (service stubs)
• No Hibernate / JPA in DTOs – these are pure transfer objects
• No business logic in controller/resource – only delegation to service
• UnsupportedOperationException as placeholder – signals "not yet implemented"
• Co-Author: @author Co-Author: Claude (claude-sonnet-4-6, Anthropic) – generated via openapi

Position in Workflow

[spec-feature]      optional – business requirements
        |
[openapi]           <-- create spec OR extend OR generate code
        |
[java-scaffold]     framework: DB, messaging, infra – do NOT regenerate REST/DTOs
        |
[review]            code review
        |
[doc]               project documentation

Important for java-scaffold: If openapi has already generated code, do not regenerate boundary/rest/ and entity/dto/ classes – only generate the rest of the project framework (pom.xml, docker-compose, application.properties, Flyway, architecture test).