openapi-ts-v0

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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)

适用于：使用
```
@hey-api/openapi-ts
```
从 OpenAPI 3.0 规范生成 TypeScript 客户端
不包括：编写 OpenAPI 规范、API 服务器实现（参见 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

```
@hey-api/openapi-ts
```
v0+
OpenAPI 3.0 规范格式
TypeScript v5+，启用 strict mode
默认输出仅包含类型和客户端；在消费应用中手写 React Query hooks

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

从 OpenAPI 规范生成客户端（单一事实来源）
客户端方法完全根据 OpenAPI 规范进行类型化
错误响应根据 OpenAPI 错误 schema 进行类型化
使用
```
createClient
```
工厂实例化客户端
在配置文件中配置输出格式和 schema 类型
Zod schemas 和生成的 React Query 插件是可选附加项

Constraints

约束

MUST

必须

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

使用
```
openapi-ts.config.ts
```
进行配置
在代码中使用客户端前先生成客户端
处理
```
response.error
```
，以支持类型化错误响应

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

使用 Prettier 格式化（
```
output.format: 'prettier'
```
）
生成 TypeScript enums（
```
types.enums: 'typescript'
```
）
基于生成的客户端手写 TanStack Query hooks
仅在需要运行时验证时添加 Zod schemas（
```
schemas.type: 'zod'
```
）
仅当项目选择启用时添加生成的 React Query 插件

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)

消费由 fastify 生成的 OpenAPI 规范
与 next 配合用于 API 客户端调用
与 TanStack Query 集成（参见 React Query Integration）

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

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

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.

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

请参阅 Config Template 获取完整示例。

References

参考资料

React Query Integration - Using generated clients with TanStack Query

React Query Integration - 使用生成的客户端配合 TanStack Query