openapi-typescript 安装、配置、卸载、介绍

安装npm install -D openapi-typescript配置在package.json中添加生成代码的脚本命令scripts: {gen-api: openapi-typescript http://localhost:8080/v3/api-docs --output src/api/generated.ts}scripts: { dev: vite, build: run-p type-check \build-only {}\ --, preview: vite preview, build-only: vite build, format: prettier --write src/**/*.{ts,vue}, type-check: vue-tsc --build --force, gen-api: openapi-typescript http://localhost:8080/v3/api-docs --output src/api/generated.ts },卸载npm uninstall openapi-typescript介绍openapi-typescript是一个专注于将 OpenAPI 规范转换为纯 TypeScript 类型定义的工具。它利用 Node.js 环境无需 Java 或运行后端服务即可快速生成类型能显著提升前后端协作的效率与代码质量。✨ 核心特性与优势⚡️ 极致性能生成的是不包含任何运行时代码的纯静态类型处理大型 API 规范如数千个端点也能在毫秒级完成且不会增加应用的最终打包体积。 零依赖与轻量只需 Node.js 环境推荐 20.x 或更高版本无需 Java、node-gyp 或运行 OpenAPI 服务器极大降低了使用门槛和项目复杂度。 类型精准完美支持 OpenAPI 3.0 和 3.1 规范能准确处理discriminators鉴别器、allOf等高级特性确保生成的类型与 API 设计保持高度一致。 快速上手指南1. 安装与配置将openapi-typescript作为开发依赖安装bashnpm i -D openapi-typescript为了让生成的类型正常工作建议在tsconfig.json中进行以下配置模块解析设置moduleResolution为Bundler或NodeNext。严格索引访问开启noUncheckedIndexedAccess: true这能避免潜在的运行时错误提高类型安全性。2. 生成类型使用npx命令指定你的 OpenAPI 规范文件支持本地 YAML/JSON 或远程 URL和输出路径即可生成类型定义文件bash# 从本地文件生成 npx openapi-typescript ./path/to/schema.yaml -o ./path/to/schema.d.ts # 从远程 URL 生成 npx openapi-typescript https://api.example.com/openapi.json -o ./path/to/schema.d.ts3. 在项目中使用生成的文件主要导出paths和components等核心类型你可以通过 TypeScript 的类型索引来精确获取所需类型。typescriptimport type { paths, components } from ./path/to/schema.d.ts; // 获取一个组件例如 User 模型 type User components[schemas][User]; // 获取特定端点 GET 请求的路径参数类型 type GetUserParams paths[/users/{id}][get][parameters][path]; // 获取特定端点 GET 请求的成功响应类型 type GetUserResponse paths[/users/{id}][get][responses][200][content][application/json][schema]; 进阶用法打造类型安全的 API 客户端openapi-typescript生成的类型非常适合与openapi-fetch搭配使用后者是一个轻量级的、基于 Fetch API 的 HTTP 客户端。这种组合能让你获得端到端的类型安全体验。安装openapi-fetchbashnpm i openapi-fetch创建并配置客户端typescript// api.ts import createClient from openapi-fetch; import type { paths } from ./path/to/schema.d.ts; const client createClientpaths({ baseUrl: https://api.example.com/v1 }); export const { GET, POST, PUT, DELETE } client;调用 API享受类型安全typescript// 在你的业务代码中 import { GET } from ./api; const fetchUser async (id: number) { // GET 方法的参数、路径、查询字符串和响应都会被自动推导 const { data, error } await GET(/users/{id}, { params: { path: { id } }, }); if (error) { console.error(error); return; } // data 的类型会自动匹配 paths[/users/{id}][get][responses][200] 中定义的结构 console.log(data); };通过这种方式API 的请求和响应都拥有了完整的类型提示和编译时检查能极大提升开发体验和代码健壮性。 核心类型深度解析openapi-typescript生成的.d.ts文件主要包含以下核心类型你可以利用它们构建各种业务逻辑类型用途paths存放所有 API 端点信息是类型推导的入口openapi-fetch等工具会依赖它。components存放可复用的数据结构如schemas数据模型、parameters参数、responses响应。operations为每个 API 操作GET, POST等生成唯一的类型别名便于直接引用。webhooks存放 API 中定义的 Webhook 相关类型用于处理回调场景。 工具对比总结在选择工具时可以这样权衡特性openapi-typescriptswagger-typescript-apiopenapi-typescript-codegen核心产出纯 TypeScript 类型完整的 API 客户端含请求函数API 客户端及类型运行时开销零有包含请求逻辑有包含请求逻辑灵活性/自由度高。只提供类型可与任何 HTTP 客户端自由搭配中。提供现成的客户端代码但可能需要适应其风格中。提供现成的客户端代码适用场景希望类型与业务代码分离或需要自定义请求逻辑的项目希望开箱即用能快速生成完整客户端代码的项目类似swagger-typescript-api 适用场景openapi-typescript是一个追求纯粹和极简的工具非常适合以下情况使用 OpenAPI 规范的 TypeScript 项目它是最核心的应用场景为项目提供基础类型保障。追求零运行时开销如果你只需要类型检查不希望引入任何无关的运行时代码它是理想之选。想要完全控制请求逻辑相比生成完整客户端代码的工具openapi-typescript让你能自由搭配fetch、axios等任何库拥有最高的灵活性。总的来说如果你认同“类型与实现分离”的理念并希望在项目中获得最高灵活性和最纯粹的 TypeScript 类型体验openapi-typescript是一个非常合适的选择。