Skill: openapi-ts

Scope

• Applies to: Generating TypeScript clients from OpenAPI 3.0 specifications using @hey-api/openapi-ts

• Does NOT cover: Writing OpenAPI specs, API server implementation (see fastify)

Assumptions

• @hey-api/openapi-ts v0+

• OpenAPI 3.0 specification format

• TypeScript v5+ with strict mode

• Zod for runtime validation (when using Zod schemas)

Principles

• Generate clients from OpenAPI specs (single source of truth)

• Use generated Zod schemas for runtime validation

• Client methods are fully typed from OpenAPI spec

• Error responses are typed from OpenAPI error schemas

• Use createClient factory for client instantiation

• Configure output format and schema type in config file

Constraints

MUST

• Use openapi-ts.config.ts for configuration

• Generate clients before using in code

• Handle response.error for typed error responses

SHOULD

• Use Zod schemas (schemas.type: 'zod' ) for runtime validation

• Use Prettier formatting (output.format: 'prettier' )

• Generate TypeScript enums (types.enums: 'typescript' )

AVOID

• Manually editing generated code

• Using generated clients without error handling

• Mixing generated and manual client code

Interactions

• Consumes OpenAPI specs generated by fastify

• Works with nextjs for API client usage

• Integrates with TanStack Query (see React Query Integration)

Patterns

Configuration Pattern

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

export default defineConfig({ input: './openapi.json', output: { path: './src/gen', format: 'prettier', }, types: { enums: 'typescript', }, schemas: { type: 'zod', }, })

Client Usage Pattern

import { createClient } from './gen/client'

const client = createClient({ baseUrl: 'https://api.example.com', })

const response = await client.GET('/users/{id}', { params: { path: { id: '123' } }, })

if (response.error) { // Handle typed error return }

// response.data is typed from OpenAPI spec

See Config Template for complete example.

References

• React Query Integration - Using generated clients with TanStack Query