Swagger/OpenAPI 生成 TypeScript 代码：最佳工具

Swagger/OpenAPI 生成 TypeScript 代码：工具完整指南

使用 TypeScript 开发现代 Web 应用与创建类型安全的 API 客户端密不可分。为每个端点手动编写接口是一项繁琐且容易出错的任务。幸运的是，存在一种强大的方法——从 OpenAPI (Swagger) 规范自动生成 TypeScript 代码。在本文中，我们将详细介绍完成此任务的最佳工具、它们的功能以及使用示例。

为什么要使用 OpenAPI 代码生成？

OpenAPI（原名 Swagger）是一种描述 REST API 的标准。使用 YAML 或 JSON 格式的规范文件，您可以获得：

• 100% 类型化 — 精确匹配请求和响应模式的 TypeScript 接口
• 与后端同步 — 当 API 发生变化时，只需重新生成代码
• 减少错误 — TypeScript 编译器在开发阶段捕获类型不匹配
• IDE 自动补全 — IntelliSense 提示字段和类型

从 OpenAPI 生成 TypeScript 的顶级工具

1. openapi-typescript-codegen（推荐）

该工具因其简单性和现代方法而广受欢迎。它生成干净、结构良好的代码，支持 axios 或 fetch。

安装：

npm install -D openapi-typescript-codegen

使用示例：

npx openapi-typescript-codegen --input ./spec.yaml --output ./generated --client axios

生成的代码：

// generated/models/User.tsexport interface User {    id: number;    name: string;    email: string;    role: 'admin' | 'user';}

// generated/services/UserService.tsexport class UserService {    public async getUsers(): Promise<User[]> {        return this.httpRequest.request({            method: 'GET',            url: '/users',        });    }}

优点：

• 支持 OpenAPI 3.0 和 3.1
• 生成模型、服务和请求类型
• 可选生成 React Query 的钩子
• 通过 Handlebars 可自定义模板

2. OpenAPI Generator (openapi-generator)

来自 OpenAPI 社区的官方生成器。支持超过 50 种语言，包括 TypeScript（多个生成器）。

安装：

npm install -D @openapitools/openapi-generator-cli

使用示例：

npx openapi-generator-cli generate \    -i spec.yaml \    -g typescript-axios \    -o ./generated

生成的代码：

// generated/api.tsexport const UsersApiAxiosParamCreator = {    getUsers: async (options?: AxiosRequestConfig): Promise<RequestArgs> => {        const localVarPath = `/users`;        return {            url: localVarPath,            method: 'GET',        };    }}

特点：

• 生成器：typescript-axios、typescript-fetch、typescript-angular
• 支持授权（OAuth2、API Key）
• 生成文档和测试
• 通过 CLI 或 Maven/Gradle 插件运行

3. swagger-typescript-api

一个轻量级且快速的生成器，专注于生成干净的 TypeScript 代码，无需额外依赖。

安装：

npm install -D swagger-typescript-api

使用示例：

npx swagger-typescript-api -p ./spec.yaml -o ./generated -n api.ts

生成的