OpenAPI 转 TypeScript 生成器

在浏览器中将 OpenAPI 3.0/3.1(YAML/JSON)转换为 TypeScript 接口。支持 $ref、oneOf/allOf、enum、nullable,可选 Zod schema 输出,零上传。

  • 在浏览器中处理
  • 工具不会把输入上传到 ZeroTool 服务器
  • 免费 · 无需注册
开启包含 path 类型时,设置操作类型外层命名空间。留空时使用 Components。组件 schema 名称来自文档本身。
将生成的 schema 属性及对应 Zod 属性设为可选。Path 参数仍按自己的 required 标记处理。修改立即生效。
添加操作命名空间,包含参数、JSON 请求体及 JSON 响应类型。根命名空间用作外层名称。修改立即生效。
在 TypeScript 声明旁生成 Zod schema,输出包含 Zod import。它不是完整的 OpenAPI 验证器。修改立即生效。
用 Pet Store 规范替换输入,并按当前命名空间和选项立即生成。
清空规范、输出和状态,保留命名空间及选项。在工具内按 Ctrl/⌘+L 还会清空命名空间。
输入 YAML 或 JSON 格式的 OpenAPI 3.0 或 3.1 文档。修改输入或命名空间后等待 300 毫秒生成。解析错误会清空输出。不会获取外部引用,不支持的引用会列在状态栏。
TypeScript 输出
复制显示的完整 TypeScript,包括已启用的 path 类型和 Zod schema。输出为空时不复制。

输入 OpenAPI 文档或载入示例以生成 TypeScript。

示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。

生成内容

  • 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 的请求体和响应体。

相关工具

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 接口可不勾选。