OpenAPI Client Generation skill for Codex

Done well means: the generated client compiles with no any/unknown holes on the endpoints the app uses, names are stable across regenerations because the spec has explicit operationIds, the generator version and spec snapshot are pinned, regeneration is one command, and CI fails when the committed client drifts from the spec.

Inspect first

1. Read AGENTS.md for language, package manager, and where generated code should live.
2. Locate the spec: a repo file, a URL (/openapi.json, /v3/api-docs, /swagger.json), or a vendor download. Fetching remote specs needs network; save a copy into the repo either way.
3. Check openapi: version. Swagger 2.0 must be converted to 3.x first (for example with swagger2openapi) or many generators produce poor types.
4. Look for an existing generated client and its generator (rg -n "openapi-generator|orval|hey-api|openapi-typescript|oapi-codegen" -g '!node_modules'). Regenerate with the same tool unless the user wants a switch.

Make the spec generator-ready

npx @redocly/cli lint openapi.yaml          # or: npx @stoplight/spectral-cli lint openapi.yaml
python3 scripts/codegen_readiness.py openapi.json

codegen_readiness.py (standard library; YAML needs PyYAML or a JSON bundle first) reports missing or duplicate operationIds, non-identifier ids, inline object schemas, unresolved local $refs and operations without a 2xx response. Exit code 1 means errors.

Fixes, in order of impact:

Finding	Effect on generated code	Fix
Missing operationId	Names like getApiV1UsersId that change when paths change	Add operationId: getUser
Inline object schemas	Anonymous types (InlineResponse2001)	Move to components/schemas with a name
No 2xx schema	Return type unknown / void	Describe the success body
nullable vs type: [x, "null"] mixups	Wrong optionality	Match the spec’s 3.0 or 3.1 dialect
Missing required arrays	Every field optional	List required properties
Polymorphism without discriminator	Union types that cannot narrow	Add discriminator.propertyName

If the spec belongs to a third party, do not edit it in place. Keep the vendor file untouched and apply fixes with an overlay (redocly decorators, an OpenAPI Overlay file, or a small patch script) so the next vendor update is a clean replace.

Choose a generator

Stack and need	Default	Output
TypeScript, minimal runtime, keep native fetch	openapi-typescript + openapi-fetch	Types only + tiny typed fetch wrapper
TypeScript SDK with functions per operation, optional Zod / TanStack Query	@hey-api/openapi-ts	Generated SDK functions and types
React app wanting ready-made TanStack Query hooks and MSW mocks	Orval	Hooks per operation
Python	openapi-python-client (httpx + attrs); datamodel-code-generator for Pydantic models only	Package
Go	oapi-codegen	Types + client in one file
.NET, Java, many languages from one spec	Kiota or OpenAPI Generator (needs Java)	Full SDK

Prefer the lightest option that types the calls the app makes; heavy SDK generators add runtime classes that are hard to review.

TypeScript: openapi-typescript + openapi-fetch

npx openapi-typescript ./openapi/api.yaml -o ./src/api/schema.d.ts

// src/api/client.ts
import createClient, { type Middleware } from 'openapi-fetch';
import type { paths } from './schema';

const auth: Middleware = {
  async onRequest({ request }) {
    request.headers.set('Authorization', `Bearer ${await getToken()}`);
    return request;
  },
};

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

// usage: path, params and body are checked against the spec
const { data, error, response } = await api.GET('/users/{id}', { params: { path: { id: userId } } });
if (error) throw new ApiError(response.status, error);

TypeScript: Hey API

// openapi-ts.config.ts
import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi/api.yaml',
  output: 'src/client',
  plugins: ['@hey-api/client-fetch', '@tanstack/react-query'],
});

Run with npx @hey-api/openapi-ts. Pin the exact version in package.json; the generator’s output changes between minor versions.

Python and Go

uvx openapi-python-client generate --path openapi/api.yaml --output-path clients/acme_api --overwrite

# oapi-codegen.yaml
package: acmeapi
output: internal/acmeapi/client.gen.go
generate:
  models: true
  client: true

go get -tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest   # Go 1.24+ tool directive
go tool oapi-codegen -config oapi-codegen.yaml openapi/api.yaml

Wrap, do not edit, generated code

• Never hand-edit generated files; the next run erases the change. Put auth, retries, base URL, telemetry and error mapping in a thin wrapper or middleware.
• Retries: only for idempotent methods (GET, PUT, DELETE) or requests with an idempotency key; back off on 429 and 503 honouring Retry-After.
• Map error responses to one error type the app understands; keep the raw status and body.
• Mark generated folders in .gitattributes (src/client/** linguist-generated=true) so reviews collapse them, and exclude them from lint and coverage.

Regeneration workflow

{
  "scripts": {
    "api:fetch": "curl -fsSL https://api.example.com/openapi.json -o openapi/api.json",
    "api:gen": "openapi-typescript openapi/api.json -o src/api/schema.d.ts",
    "api:check": "npm run api:gen && git diff --exit-code -- src/api/"
  }
}

• Fetch or update the spec snapshot (network) and commit it with the generated output.
• Lint and run codegen_readiness.py.
• Generate with the pinned version.
• Type-check the whole app (tsc --noEmit, mypy, go build ./...): breaking API changes show up as compile errors at call sites; fix them in the same PR.
• Run api:check in CI so a spec change without regeneration fails the build.

Verification

• Compile: the app type-checks against the new client with no new any or // @ts-ignore.
• Contract: call one read endpoint against a dev server or recorded fixture and confirm the response parses into the generated type (with Zod or Pydantic validation where enabled).
• Diff review: read the generated diff summary; renamed functions usually mean an operationId changed.
• When a type is wrong, fix the spec (or overlay) and regenerate; do not cast at call sites.

Gotchas

• additionalProperties defaults to allowed in OpenAPI; some generators then emit index signatures that weaken types. Set it explicitly when the shape is closed.
• format: date-time becomes string in most TS generators; convert at the wrapper boundary if the app needs Date.
• Large integers (int64) overflow JavaScript numbers; keep them as strings in the spec when IDs exceed 2^53.
• Tags drive file splitting in some generators; untagged operations land in a catch-all file.
• A server spec generated from code (FastAPI, springdoc, NestJS) may differ per environment; snapshot from the deployed version the client targets.

Output

Report: spec source and version, generator and pinned version, files generated, spec fixes or overlays applied, wrapper features, call sites changed, and the CI drift check added.