OpenAPI 转 TypeScript 生成器
在浏览器中将 OpenAPI 3.0/3.1(YAML/JSON)转换为 TypeScript 接口。支持 $ref、oneOf/allOf、enum、nullable,可选 Zod schema 输出,零上传。
- 在浏览器中处理
- 工具不会把输入上传到 ZeroTool 服务器
- 免费 · 无需注册
用微信扫描以下二维码即可分享
示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。
生成内容
- components/schemas:每个 schema 输出一个
export interface或export type,对象类型用 interface,基本/联合/枚举/交叉类型用 type alias。 - $ref:
#/components/schemas/...引用会被解析为对应类型名,并按规范声明顺序输出。 - oneOf / anyOf:转为联合类型
A | B | C;allOf 转为交叉类型A & B。 - enum:转为字符串或数字字面量的联合类型。
- nullable:3.0 的
nullable: true与 3.1 的type: ['X', 'null']都转为X | null。 - format 提示:
format: date-time会附带 ISO 8601 的 JSDoc 注释;format: binary转为Blob。 - additionalProperties:转为索引签名或
Record<string, T>。
Path 类型(可选)
勾选 包含 path 类型 后,每个操作都会产出一个类型封装:
export namespace Components {
export namespace GetPetById {
export interface PathParameters {
id: number;
}
export type Response200 = Pet;
}
}
如果操作没有 operationId,工具会按 method + path 合成一个,例如 GetPetsId。
Zod schema(可选)
勾选 包含 Zod schema,会为每个 component 输出同名 XSchema:
import { z } from 'zod';
export const PetSchema = z.object({
id: z.number().int(),
name: z.string(),
status: z.enum(["available", "pending", "sold"]),
});
若你的项目是从手写 TS 类型反推 Zod,可改用 TypeScript 转 Zod。
示例:内置的 Pet Store 规范
点击示例会载入一份小型 OpenAPI 3.0.3 规范,含 Pet、NewPet 两个 schema 和三个操作。输出中的 schema 部分:
export interface Pet {
id: number;
name: string;
tag?: string | null;
status: "available" | "pending" | "sold";
photo?: Blob;
}
export interface NewPet {
name: string;
tag?: string;
}
必填属性保持必填,其余加 ?;nullable: true 加上 | null;format: binary 变成 Blob。打开包含 path 类型后,getPetById 生成 Components.GetPetById,内含 PathParameters { id: number } 和 Response200 = Pet。打开包含 Zod schema 后,生成的 PetSchema(用 zod 3.25 实测)拒绝 status: "lost",接受 tag: null。
示例:const、类型数组和外部引用
这个 OpenAPI 3.1 schema 用了 const、类型数组和指向另一个文件的引用:
openapi: 3.1.0
info: { title: Events, version: 1.0.0 }
paths: {}
components:
schemas:
Event:
type: object
required: [id, kind, createdAt]
properties:
id: { type: integer, format: int64 }
kind: { const: order.created }
createdAt: { type: string, format: date-time }
note: { type: [string, 'null'] }
owner: { $ref: 'https://example.com/schemas/user.yaml#/User' }
工具输出:
export interface Event {
id: number;
kind: "order.created";
/** ISO 8601 date-time */ createdAt: string;
note?: string | null;
owner?: unknown /* unresolved $ref: https://example.com/schemas/user.yaml#/User */;
}
type: [string, "null"] 映射为 string | null,const 映射为字面量类型 "order.created"(Zod 中为 z.literal("order.created"))。指向 user.yaml 的引用在另一个文档里,工具不会去拉取:owner 输出为 unknown,引用保留在注释里,状态栏显示「不支持:$ref 指向 https://example.com/schemas/user.yaml#/User」。先用 redocly bundle 把外部文件合并进 components,再粘贴合并后的规范。
示例:Zod 中的前向引用与递归
Zod schema 是 JavaScript 常量,定义它的那一行之前不能使用。下面的 schema 中,Order 引用了后声明的 Customer,Node 引用了自身:
components:
schemas:
Order:
type: object
required: [customer]
properties:
customer: { $ref: '#/components/schemas/Customer' }
Customer:
type: object
required: [name]
properties:
name: { type: string }
Node:
type: object
required: [value]
properties:
value: { type: string }
children:
type: array
items: { $ref: '#/components/schemas/Node' }
Zod 输出把这两处引用包进 z.lazy,在解析数据时才查找 schema,而不是在模块加载时。直接或经由其他 schema 引用自身的 schema 还会加上 z.ZodType<Node> 类型标注,因为 TypeScript 无法推断出现在自身初始化表达式里的常量类型(错误 TS7022):
export const OrderSchema = z.object({
customer: z.lazy(() => CustomerSchema),
});
export const CustomerSchema = z.object({
name: z.string(),
});
export const NodeSchema: z.ZodType<Node> = z.object({
value: z.string(),
children: z.array(z.lazy(() => NodeSchema)).optional(),
});
生成的模块在 TypeScript 5.9 严格模式下能通过编译,zod 3.25 用它能解析三层的树。
限制
- 只解析
#/components/schemas/...引用,path 类型中另含#/components/parameters/...。其他引用(URL、其他文件、#/components/responses/...)输出为unknown,并列在状态栏里。 - 不是合法 TypeScript 标识符的 schema 名会被改名:字母、数字、
_、$以外的字符改为_(pet-status→pet_status),数字开头的名字前加_,unknown、class这类关键字后加_。 - 值为对象或数组的
const输出为unknown;字符串、数字、布尔值和 null 输出为字面量类型。 format: int64的integer输出为number,超过 253 会丢精度。如果 API 把这类 ID 当字符串发送,请改成string。- path 类型只读取
application/json的请求体和响应体。
相关工具
- OpenAPI / Swagger 校验器 — 生成类型前先校验规范。
- JSON 转 TypeScript — 只有 JSON 响应样本、没有完整规范时使用。
- JSON 转 Zod Schema — 从单个 JSON 示例生成 Zod。
FAQ
支持哪些 OpenAPI 版本?
支持 3.0.x 与 3.1.x。OpenAPI 3.1 的 `type: ['string', 'null']` 写法会输出 `string | null`,OpenAPI 3.0 的 `nullable: true` 也会被识别。
支持 Swagger 2.0 吗?
按设计不支持 Swagger 2.0。请先用 editor.swagger.io(Swagger Editor 内置的转换功能)把规范升级到 OpenAPI 3.x,再粘贴到本工具。
远程 $ref 会被解析吗?
不会。只解析 `#/components/schemas/...`(path 类型中另含 `#/components/parameters/...`)。其他 `$ref`,例如 URL 或另一个文件,会输出为带注释的 `unknown`,状态栏列出所有未解析的引用。请先把规范合并成一个文件,例如用 `redocly bundle`,或改用 openapi-typescript CLI。
我的规范会被上传吗?
不会。YAML 或 JSON 在当前标签页里解析,TypeScript 也在这里生成;规范不会上传,也不保存到浏览器存储,远程 $ref 的 URL 也不会被请求。提交规范或命名空间的编辑、切换选项、或载入示例并成功生成类型且没有未解析引用后,页面统计只记录工具名和动作 generate。输入过程不记 generate,相同输出不重复计数。点「示例」另记 example_load。统计不含规范和生成的类型。
可以同时输出 Zod schema 吗?
可以。勾选 **包含 Zod schema** 即可在 TypeScript 接口旁边生成对应的 `z.object({...})`,适合需要运行时校验与静态类型保持一致的场景。
「包含 path 类型」做什么?
为每个操作生成一个命名空间,暴露 `PathParameters`、`QueryParameters`、`RequestBody`、`Response200`/`Response201` 等类型,外层用你设置的根命名空间包裹。如果只需要 DTO 接口可不勾选。