Swagger/OpenAPI 生成 TypeScript 代码：库与工具

Swagger/OpenAPI 生成 TypeScript 代码：自动化创建 API 客户端

在使用 TypeScript 开发现代 Web 应用程序时，经常需要与通过 OpenAPI 规范（以前称为 Swagger）描述的 REST API 进行集成。手动编写类型、接口和客户端代码不仅耗时，而且容易出错，尤其是在后端发生变化时。自动从 OpenAPI 规范生成 TypeScript 代码的工具应运而生。在本文中，我们将介绍三种最流行的解决方案：openapi-typescript、orval 和 swagger-typescript-api，并比较它们的功能。

为什么需要从 OpenAPI 生成 TypeScript？

主要目标是同步前端和后端之间的类型和客户端代码。自动生成的优势包括：

• 类型安全：所有端点、请求参数和响应都获得严格的 TypeScript 类型。
• 时效性：当规范发生变化时，只需重新生成代码，无需手动修改。
• 加速开发：开发者获得现成的 API 调用函数，并支持自动补全（IntelliSense）。
• 减少错误：消除字段名称中的拼写错误和类型不匹配。

openapi-typescript

openapi-typescript 库（由 openapi-fetch 的创建者开发）是一个轻量级的类型生成器。它只创建 TypeScript 接口和类型，不生成用于 API 调用的客户端代码。对于需要严格类型化数据但 API 调用方式由开发者自行决定（例如，通过 fetch 或 axios）的项目来说，这是理想的选择。

安装：

npm install -D openapi-typescript

使用示例（从 spec.yaml 文件生成类型）：

npx openapi-typescript ./spec.yaml -o ./types/api.ts

结果会得到一个包含类型的文件，可以导入使用：

import type { paths } from './types/api';

// GET /users 响应的类型type UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

优点： 极简、生成速度快、对复杂模式（allOf、oneOf）支持良好。
缺点： 没有现成的 API 调用函数，需要额外的封装。

orval

Orval 是一个强大的生成器，它不仅创建类型，还创建完整的 React Hooks，以及用于 axios、fetch 或 Angular 的客户端。它在使用 React Query（TanStack Query）的 React 项目中特别有用。

安装：

npm install -D orval

在 orval.config.ts 文件中的配置：

export default {  petstore: {    input: './swagger.yaml',    output: {      target: './src/generated',      client: 'react-query', // 或 'axios', 'fetch', 'angular'    },  },};

运行生成：

npx orval

生成的 Hook 示例：

import { useGetUsers } from './src/generated/users';

function UsersList() {  const { data, isLoading, error } = useGetUsers();  // data 将自动获得类型}

优点： 与 React Query 的现成集成、支持变更、自动缓存管理。
缺点： 生成的代码量大、与特定 HTTP 客户端绑定。

swagger-typescript-api

swagger-typescript-api 库提供灵活的生成方式：既可以获得简单的类型，也可以获得支持多种 HTTP 客户端（axios、fetch）的完整 API 客户端。其显著特点是支持自定义生成模板。

安装：