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
• Default output is types and client only; React Query hooks are handwritten in consuming apps

Principles

• Generate clients from OpenAPI specs (single source of truth)
• 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
• Zod schemas and generated React Query plugins are optional add-ons

Constraints

MUST

• Use openapi-ts.config.ts for configuration
• Generate clients before using in code
• Handle response.error for typed error responses

SHOULD

• Use Prettier formatting (output.format: 'prettier')
• Generate TypeScript enums (types.enums: 'typescript')
• Write TanStack Query hooks by hand against the generated client
• Add Zod schemas (schemas.type: 'zod') only when runtime validation is required
• Add generated React Query plugin only when the project opts into it

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 next 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',
  },
})

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