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

References

• React Query Integration - Using generated clients with TanStack Query