openapi-typescript 用于 TypeScript：完整指南及示例

\n\n

在现代 Web 开发中，API 接口扮演着关键角色，而使用 OpenAPI（原 Swagger）标准对其进行规范已成为事实上的标准。然而，手动维护与 OpenAPI 规范相匹配的 TypeScript 类型是一个耗时且容易出错的过程。openapi-typescript 库解决了这个问题，它能基于您的 OpenAPI 模式（v3.0 和 v3.1）自动生成严格的 TypeScript 类型。

\n\n

该库的主要目标是确保与 API 进行类型安全（type-safe）的交互。您无需为每个端点手动声明接口，只需运行生成器，它就会为所有请求、响应、参数和模式创建一个（或多个）包含类型的文件。这不仅节省了时间，还保证了您的类型始终与 API 的最新版本同步。如果规范发生变化，只需重新生成类型，TypeScript 编译器就会立即指出代码中的所有不匹配之处。

\n\n

该库广泛应用于对可靠性和开发速度要求较高的项目中：从微服务架构到单页应用（SPA）。它支持为客户端（例如，用于 fetch 或 axios）和服务器端（例如，用于 Express 或 Fastify）生成类型。在本文中，我们将详细介绍安装、主要方法、实际示例和常见错误。

\n\n

安装

使用 npm 或 yarn 安装该库。该命令将同时安装生成器本身及其必要的依赖项。

\n\n

npm install openapi-typescript typescript @types/node --save-dev

\n\n

或者通过 yarn：

\n\n

yarn add -D openapi-typescript typescript @types/node

\n\n

如果您计划在运行时使用生成的类型（例如，用于验证），请额外安装 openapi-typescript-helpers：

\n\n

npm install openapi-typescript-helpers

\n\n

快速入门——最小工作示例

假设您有一个包含 OpenAPI 规范的文件 spec.yaml。让我们创建一个简单的脚本来生成类型。

\n\n

// generate.ts\nimport { createClient } from 'openapi-typescript';\nimport * as fs from 'fs';\n\nasync function main() {\n  const spec = fs.readFileSync('./spec.yaml', 'utf-8');\n  const result = await createClient(spec, { format: 'yaml' });\n  fs.writeFileSync('./api-types.d.ts', result);\n  console.log('类型已生成至 api-types.d.ts');\n}\n\nmain().catch(console.error);

\n\n

运行脚本：

\n\n

npx ts-node generate.ts

\n\n

之后，文件 api-types.d.ts 中将包含与您的规范相对应的所有类型。现在您可以在项目中导入它们：

\n\n

import type { paths, components } from './api-types';\n\n// 使用特定端点的类型\ntype GetUsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

\n\n

主要方法和函数

\n\n

1. `createClient(schema: string, options?: ClientOptions): Promise<string>`

功能： 生成类型的主要方法。接收一个包含规范（JSON 或 YAML）的字符串，并返回一个包含 TypeScript 代码的字符串。

import { createClient } from 'openapi-typescript';\nimport * as fs from 'fs';\n\nconst spec = fs.readFileSync('./spec.json', 'utf-8');\nconst types = await createClient(spec, { format: 'json' });\nfs.writeFileSync('./types.d.ts', types);

\n\n