OpenAPI Codegen skill for Claude Code

Done well means: one spec is the source of truth, generation is a single scripted command pinned to exact tool versions, CI fails when committed output is stale or the spec breaks existing clients, and generated code is never edited by hand.

Workflow

- [ ] 1. Decide spec-first or code-first and where the spec lives
- [ ] 2. Make the spec codegen-ready (run the readiness check)
- [ ] 3. Pick the generator per target with the decision table
- [ ] 4. Pin versions and script generation
- [ ] 5. Decide commit-or-build for generated output
- [ ] 6. Add CI gates: lint, breaking diff, drift, typecheck

1. Source of truth

Situation	Approach
API consumed by other teams, mobile, or partners	Spec-first: edit openapi.yaml, generate server interfaces and clients
Framework emits accurate specs (FastAPI, ASP.NET Core MapOpenApi, springdoc, NestJS swagger)	Code-first: export the spec in CI, commit it, generate clients from the exported file
Spec hand-written but server hand-coded	Spec-first plus response validation in contract tests, or drift is guaranteed

For code-first, export to a committed file (for example GET /openapi.json in a test or a CLI export step) so reviewers see spec diffs in PRs.

2. Make the spec codegen-ready

Generators turn spec shape directly into names and types. Fix these before generating:

• Every operation has a unique, stable operationId (listOrders, getOrder); it becomes the function or hook name. Renaming it is a breaking change for generated clients.
• Request and response bodies reference named schemas in components/schemas. Inline objects produce names like GetOrders200ResponseDataItem.
• required arrays are accurate; missing ones make every field optional.
• Nullability: 3.1 uses type: [string, "null"]; 3.0 uses nullable: true. Mixing produces wrong types.
• oneOf / anyOf unions have a discriminator with propertyName so generators emit tagged unions instead of unknown or giant intersections.
• Operations carry tags; generators split files by tag.
• Every operation declares at least one 2xx response with a schema (or explicit 204).

Run the bundled checker on a JSON spec (bundle YAML first):

npx @redocly/cli bundle openapi.yaml --output openapi.bundled.json
python3 scripts/codegen_readiness.py openapi.bundled.json

It reports missing or duplicate operationIds, inline object bodies, unions without a discriminator, untagged operations, undeclared path parameters, and operations without a 2xx schema, and exits 1 on errors. If PyYAML is installed it also reads YAML directly.

3. Choose the generator

Target	Default	Why / escape hatch
TypeScript, lightweight fetch client	openapi-typescript + openapi-fetch	Types only, no runtime per endpoint, tiny bundle
TypeScript + TanStack Query hooks, MSW mocks, Zod	orval	Hooks and mocks from one config
TypeScript, plugin-based (SDK, Zod, TanStack Query)	@hey-api/openapi-ts	Active, flexible; pre-1.0, so pin exact versions
Java, Kotlin, Python, Go, C#, many others; server stubs	openapi-generator	Broadest language coverage; quality varies per generator
Go server and client	oapi-codegen (strict server)	Idiomatic net/http, chi, echo, gin interfaces
.NET, Java, Go, Python, TS clients from one tool	Kiota	Microsoft-maintained, consistent across languages

Prefer one generator per language across the org; mixing them means two sets of naming rules for the same API.

4. Pin and script

openapi-typescript + openapi-fetch

npm i -D openapi-typescript@7 && npm i openapi-fetch
npx openapi-typescript ./openapi.yaml -o ./src/api/schema.d.ts

import createClient, { type Middleware } from "openapi-fetch";
import type { paths } from "./api/schema";

const api = createClient<paths>({ baseUrl: import.meta.env.VITE_API_URL });

const auth: Middleware = {
  onRequest({ request }) {
    request.headers.set("Authorization", `Bearer ${getToken()}`);
    return request;
  },
};
api.use(auth);

const { data, error } = await api.GET("/orders/{orderId}", {
  params: { path: { orderId } },
});
if (error) throw new ApiError(error);   // error typed from the spec's error responses

orval (orval.config.ts)

import { defineConfig } from "orval";

export default defineConfig({
  orders: {
    input: { target: "./openapi.yaml" },
    output: {
      mode: "tags-split",
      target: "src/api/gen",
      schemas: "src/api/gen/model",
      client: "react-query",
      httpClient: "fetch",
      mock: true,          // MSW handlers with faker data
      clean: true,
    },
  },
});

Option names shift between orval majors; confirm against npx orval --help and the docs for the pinned version.

openapi-generator (Java runtime required; the npm wrapper downloads the JAR)

npx @openapitools/openapi-generator-cli version-manager set 7.14.0   # writes openapitools.json
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g spring -o server/generated \
  --additional-properties=interfaceOnly=true,useSpringBoot3=true,useTags=true
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g python -o clients/python \
  --additional-properties=packageName=acme_client

Use the latest 7.x the team has validated; the version above is an example. Use .openapi-generator-ignore to protect hand-written files, and generate server code as interfaces (interfaceOnly, delegatePattern) so implementations live outside the generated directory.

oapi-codegen (Go 1.24+ tool dependency)

go get -tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
go tool oapi-codegen -config oapi.yaml openapi.yaml

# oapi.yaml
package: api
output: internal/api/api.gen.go
generate:
  std-http-server: true
  strict-server: true
  models: true

Wrap every invocation in one script (npm run gen:api, make gen) so CI and humans run the identical command.

5. Commit or generate at build time

Commit generated code when	Generate at build when
Reviewers should see API changes as code diffs	Output is large and noisy
Consumers build without Java/Node generator toolchains	Every build environment has the generator pinned
Go projects (convention: go generate output is committed)	Single-repo TS app where postinstall/prebuild runs it

Either way, mark generated paths in .gitattributes (linguist-generated=true) and exclude them from lint and coverage. Never hand-edit generated files; fix the spec or the template.

6. CI gates

npx @redocly/cli lint openapi.yaml
oasdiff breaking origin-main-openapi.yaml openapi.yaml --fail-on ERR
npm run gen:api && git diff --exit-code -- src/api/gen   # drift check if committed
npx tsc --noEmit                                           # consumers still compile

The typecheck after regeneration is the most valuable gate: a changed field shows up as a compile error at every call site that depends on it.

Gotchas

• format: date-time becomes string in most TS generators; convert at the boundary rather than lying in the type.
• Integer IDs above 2^53 lose precision in JS; spec them as strings.
• additionalProperties omitted means “allowed” in JSON Schema; some generators then add index signatures that weaken types. Set additionalProperties: false where intended.
• Enum additions break exhaustive switch statements in generated clients; document enums as open or handle a default branch.
• A spec served by the running app can differ from the committed one (feature flags, environment-dependent routes); diff them in CI for code-first setups.
• Generators handle allOf inheritance inconsistently; prefer composition with a discriminator over deep allOf chains.

Verification

1. python3 scripts/codegen_readiness.py reports no errors.
2. Regenerating from a clean checkout yields zero diff.
3. oasdiff breaking is empty or every item is approved with a migration note.
4. Consumers typecheck, and one integration test calls the real server through the generated client.

When the generated output looks wrong, fix the spec first (names, required, discriminator), regenerate, and only then consider generator options or custom templates.