generate-api-code

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Code Generation

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

**Usage:** `/architect:generate-api-code [--service=<name>] [--out=<path>] [--confirm-versions|--no-confirm-versions] [--dry-run] [--auto] [--lang=en|ja]`

## Desired Outcome

The layer between the wire and the domain, generated from the contract rather than from an idea of
what the contract probably says:

- **Controllers** — one handler method per `operationId`, 1:1, named from it
- **Request DTOs** — from `components/schemas`, with Bean Validation derived from the schema constraints
- **Response DTOs** — carrying exactly the declared properties, and nothing the domain might grow later
- **Mappers** — explicit DTO ↔ domain conversion, field by field
- **Exception handler** — `@RestControllerAdvice` producing RFC 9457 Problem Details for every
  registered problem type
- **The contract map** — `reports/06_implementation/api-contract-map.{md,json}`, the record of what
  was bound to what

This is the layer that closes the loop between `design-api` and the domain code
`generate-scalardb-code` (or the data-layer equivalent) emits. Without it the OpenAPI document is a
report, not a contract.

## Package Ownership (the seam)

Two codegen skills write into one service tree, so the boundary is explicit — neither overwrites the
other's packages:

| Package | Owner |
|---------|-------|
| `…/api/` — controllers, DTOs, mappers, error handling, API configuration | **this skill** |
| `…/domain/`, `…/infrastructure/` — entities, repositories, domain services, transaction management | `/architect:generate-scalardb-code` (or the data-layer generator) |
| `…/application/` — application services (the transaction boundary) | this skill generates the interface and the call from the controller; the implementation body belongs to the domain generator, which is why the two are run together |
| `…/usecase/` + `…/api/presenter/` — when `api-layer-spec.md` declares `layering_style: clean` | this skill generates, per operation, the input boundary (`execute(<Op>InputData)`), the domain-free input/output data records (plus shared ones such as `MoneyData`, `PrincipalData`), the output boundary (`void present(<Op>OutputData)`), the request-scoped presenter under `api/presenter/`, and the exception types the contract's problem types make the handler branch on (they must live in `usecase/`, which never imports `api/`); the interactor body, `usecase/tx/`, `view/`, `worker/` and shared collaborators belong to the domain generator. `…/application/` is not created; on a style switch it is still present until `generate-scalardb-code` migrates it, and the handler imports the transaction exceptions from wherever they currently are |

A generated controller never imports a persistence or ScalarDB type. That is a rule this skill obeys
and `generate-contract-tests` enforces with ArchUnit.

## Contract Constraints (binding)

@rules/api-contract-fidelity.md §5 governs every file this skill writes. Restated because it is the
whole point of the skill:

1. **Generate only what the specification declares** — no endpoint, parameter, field, header, or
   status code beyond it. Not a health endpoint, not a debug route, not a convenient extra field.
2. **Names come from the specification** — DTO names from `components/schemas` keys, method names
   from `operationId`. Do not re-style them.
3. **Validation is derived, not chosen** — `minLength` → `@Size`, `pattern` → `@Pattern`, `enum` → an
   enum type, `required` → `@NotNull`; the request DTO is `@Valid` at the boundary.
4. **The request DTO is never the domain object or the entity** — an explicit mapper stands between
   them, mapping only declared fields. Binding a body onto an entity is the mass-assignment defect.
5. **The response DTO is never the domain object either.**
6. **Errors leave only through the Problem Details handler** — no ad-hoc `ResponseEntity.status(...)`
   anywhere, and no second error envelope.
7. **Write the contract map last.** A run that emits code and no map is incomplete.

**When the specification is missing something, stop — do not fill it in.** An operation with no
declared authorization, an inline anonymous schema, an undeclared status code: report it as a
contract-quality finding and ask per @rules/open-questions.md. Generating a plausible guess is how
the contract silently stops being the contract.

## Error Handling

The `@RestControllerAdvice` covers every row of @rules/api-error-standard.md §3, and
`UnknownTransactionStatusException` gets **its own branch** — never the generic 500 handler. The
commit may have succeeded, so it is 503 with `Retry-After` when the operation is idempotency-key
protected and 500 with no retry hint otherwise, both carrying the transaction ID as an extension
member, neither rolling back (§3.1). Getting this wrong is a blocker-severity finding in
`verify-implementation`, so generate it deliberately rather than by pattern.

`detail` strings never interpolate a §4-prohibited value — no stack traces, SQL, namespace or table
names, internal hosts, or fields the data classification marks confidential. The operator-facing
detail goes to the log, joined by `trace_id`.

Where an operation declares an `Idempotency-Key` obligation, generate the key handling with the
idempotency record written **inside the business transaction** (@rules/api-error-standard.md §5) —
a record committed separately reintroduces the duplicate the key exists to prevent.

## The Build Must Accept What Was Generated

The API layer brings its own runtime dependencies, and code the project cannot compile is not a
deliverable. Before finishing, add every dependency the generated layer requires and **verify the
module compiles** — a run that emits sources and leaves the build broken has produced nothing usable.

The ones most often missed, because the design implies them without naming them:

| Generated because the design says… | Dependency |
|---|---|
| OIDC / JWT authentication, `@AuthenticationPrincipal Jwt` | `spring-boot-starter-oauth2-resource-server` |
| Bean Validation on DTOs | `spring-boot-starter-validation` |
| `@PreAuthorize` method-level authorization | `spring-boot-starter-security` (and method security enabled — the annotation is silently inert without it) |
| ScalarDB exception types in the handler | the ScalarDB artifact for the pinned edition |

`@PreAuthorize` deserves the emphasis: it compiles, reads as an authorization control, and enforces
nothing until method security is switched on. Generate the enabling configuration alongside it, or
the security review finds an operation whose declared authorization exists only as an annotation.

Run the compile before writing the contract map, and report the command and its exit code in the run
summary — the same evidence standard the quality gate applies (@rules/ai-code-quality-gate.md).

## Dependency Versions

Any build file this skill touches pins versions, so follow @rules/dependency-versions.md: resolve
Spring Boot, Java, the validation implementation, and the OpenAPI tooling from their registries,
choose stable mutually compatible releases, and never copy the illustrative numbers out of
@rules/spring-boot-integration.md. Reuse `work/version-decisions.json` when its entries are fresh
rather than re-resolving and drifting. Confirm per `--confirm-versions` / `--no-confirm-versions` /
`options.confirm_versions`.

## Outbound Clients (the other half of the HTTP surface)

`generate-scalardb-code` emits the outbound ports a service needs (`domain/port/InventoryPort`,
`PaymentPort`, …) and their Fakes; this skill emits their **adapters** under
`infrastructure/client/`, each bound to the *called* service's OpenAPI contract by `operationId`
exactly as the inbound controllers are (@rules/api-contract-fidelity.md), with the Problem Details
of the callee mapped to the port's declared outcomes, timeouts from `operation-contracts.md`, and
the idempotency key forwarded where the callee requires one, the callee's `security` scheme

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect