# openapi-typesafe —— 类型安全的 OpenAPI 客户端,已为 TypeScript 7 做好准备

openapi-typescript 和 openapi-fetch 的作者在 2026 年 9 月停止了维护,这是它们的一个持续维护、可直接替换的继任者。它根据 OpenAPI 3.0、3.1 或 3.2 schema 生成 TypeScript 类型,并给你一个完全类型化的 fetch 客户端。生成器不再使用 TypeScript 编译器 API,所以能在 TypeScript 5、6 和 7 上运行。每次发布都会用 1,820 个真实 schema 做检查:50,960 个用例,0 个意外差异。

- **Author:** Fedor Chishchin
- **Role:** 维护者——fork、重写生成器、兼容性测试、发布流水线
- **Period:** 2026 年 11 月 —— 至今
- **Stack:** TypeScript · Node.js · OpenAPI 3.x · Vitest · GitHub Actions · npm provenance · VitePress
- **Source:** https://fedorthinks.com/zh/work/openapi-typesafe

---

<PackageBadges npm="openapi-typesafe" />

先生成类型,再用类型化的客户端调用你的 API:

<Command>npx openapi-typesafe ./openapi.yaml -o ./src/api/schema.d.ts</Command>

## 为什么要做它

[openapi-typescript](https://github.com/openapi-ts/openapi-typescript) 和 `openapi-fetch`
是很多 TypeScript 团队对接 API 的方式:把一个 OpenAPI schema 交给它们,就能得到每个路径、参数和响应的类型。2026 年 9 月,它们的作者
[停止了维护](https://github.com/openapi-ts/openapi-typescript/issues/2874)。

与此同时,TypeScript 7 来了。它是编译器的原生移植版,它的 `typescript` 包没有 JavaScript API:没有 `ts.factory`,也没有 printer。openapi-typescript 的每个类型都是用 `ts.factory` 构建的,所以在 TypeScript 7 的项目里,它要么装不上,要么一加载就崩溃。

于是,成千上万个项目手里有了一个既没人维护、又马上要坏掉的依赖。

## 我做了什么

我带着完整的上游历史 fork 了它,并定下一条规则:**迁移只能是改个包名,别的什么都不用动。** 同样的 CLI 参数、同样的 Node API、同样的生成结果、同样的客户端。

- **一个不依赖编译器 API 的生成器。** 类型被构建成我们自己的一棵小树,再由我们自己的 printer 打印出来。它完全不需要 `typescript` 包,所以能和 TypeScript 5、6 或 7 一起运行。
- **支持 OpenAPI 3.2**,原版会直接拒绝它。
- **一个迁移工具** (`openapi-typesafe-migrate`),帮你把项目迁过来:imports、脚本和包配置。
- **TanStack Query 绑定** 和共享的类型辅助工具,同样可以直接替换。

## 我怎么知道它是兼容的

"可直接替换"是一个承诺,所以必须测量,而不是嘴上说说。一份公开的
[兼容性报告](https://openapi-typesafe.github.io/openapi-typesafe/compatibility)
把我们的输出和 openapi-typescript 7.13 在 **1,820 份真实 OpenAPI 文档** 上做对比:整个 APIs.guru 目录,再加上 GitHub、Stripe、OpenAI、Cloudflare 和 Kubernetes 这样的大家伙。每个 schema 用 28 组选项运行,所以一共是 **50,960 个用例**。

每个用例分三步检查:先看字节是否相同,再看类型是否相同(严格的同一性检查),最后看能不能编译。最近一次运行:**99.87% 逐字节相同,100% 类型相同,0 个意外差异**。CI 每晚跑一遍完整语料,每次发布都会附上它的报告链接。

## 安全的发布

代码生成器在你的机器上运行,并往你的项目里写代码,所以它的供应链很重要:

- 依赖尽量少;
- npm provenance,没有长期有效的发布令牌;
- 威胁模型、带响应时限的安全策略,以及私密的漏洞报告渠道;
- OpenSSF Scorecard 和 OpenSSF Best Practices 徽章。

## 为编码代理而做

仓库里附带一个 **agent skill**,教 Claude Code(或任何能读取 skills 的代理)如何配置客户端、发起类型化调用、处理错误,以及从 openapi-typescript 迁移过来。另有一套独立的 eval 用 34 个编码任务来衡量这个 skill。文档站提供 `llms.txt`、`llms-full.txt`,以及每个页面的 Markdown 副本。

我用 agentic engineering 的方式构建了它:编码代理写代码,而我负责设计、兼容性规则,以及证明这条规则成立。

## 状态

候选发布版:npm 上的 `1.0.0-rc.4`。在 1.0.0 之前,名称和输出仍可能变化;之后遵循语义化版本。MIT 许可证。