openapi-codegen
How to consume a new backend API surface via Orval-generated OpenAPI clients — only relevant once the project has a real OpenAPI spec to generate from.
SKILL.md.claude/skills/openapi-codegen/SKILL.md
GitHubThis template ships with a hand-written mock API (src/mocks/handlers.ts, MSW) and no OpenAPI
spec — this skill only becomes relevant once the project this template was cloned into has a
real backend with a published OpenAPI document. It is manual-invocation-only (/openapi-codegen)
so it never loads by accident while there is nothing to generate from.
When there is a real spec:
- Add
orval(already pinned as a compatible default indocs/CUSTOMIZING.md) and anorval.config.tspointing at the spec (a URL or a committed.json/.yamlfile). - Generate into
src/lib/generated/(gitignored or committed — decide per project; committing makes diffs reviewable, gitignoring keeps CI as the source of truth) — configure Orval'sclientoutput mode toreact-queryso it emitsuseQuery/useMutationhooks directly, consistent with theserver-state-tanstack-queryskill's conventions. - Never hand-edit a generated file — if the generated hook shape doesn't fit a call site,
wrap it in a thin hand-written hook in
src/lib/queries.tsinstead. - Re-run generation as a
pnpmscript (orval) wired intoscripts/verify.sh's typecheck step's prerequisites if the project's CI needs generated types to be fresh — otherwise generation is a manual step run when the spec changes. - Validate the generated response shape against a Zod schema at the boundary if Orval's output doesn't already do so — Orval generates TypeScript types, not runtime validation, by default.