AgentSkillsCN

Hey API Codegen

利用 @hey-api/openapi-ts 从 OpenAPI 规范中生成 TypeScript 客户端。借助 Zod 架构，打造类型安全的 API 客户端。 当您需要为前端或 API 消费者生成 TypeScript 客户端时，可选用此技能。

SKILL.md
--- frontmatter
name: Hey API Codegen
description: |
  Generate TypeScript clients from OpenAPI specs using @hey-api/openapi-ts. Type-safe API clients with Zod schemas.
  
  Use when: generating TypeScript clients from OpenAPI specifications for frontend or API consumers.

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

Patterns

Configuration Pattern

typescript
// 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

typescript
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