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作为开发依赖安装：
bash
npm 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.ts
3. 在项目中使用
生成的文件主要导出paths和components等核心类型，你可以通过 TypeScript 的类型索引来精确获取所需类型。
typescript
import 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-fetchbash
npm i openapi-fetch
创建并配置客户端
typescript
// api.ts import createClient from 'openapi-fetch'; import type { paths } from './path/to/schema.d.ts'; const client = createClient<paths>({ 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-typescript | swagger-typescript-api | openapi-typescript-codegen |
|---|---|---|---|
| 核心产出 | 纯 TypeScript 类型 | 完整的 API 客户端（含请求函数） | API 客户端及类型 |
| 运行时开销 | 零 | 有（包含请求逻辑） | 有（包含请求逻辑） |
| 灵活性/自由度 | 高。只提供类型，可与任何 HTTP 客户端自由搭配 | 中。提供现成的客户端代码，但可能需要适应其风格 | 中。提供现成的客户端代码 |
| 适用场景 | 希望类型与业务代码分离，或需要自定义请求逻辑的项目 | 希望开箱即用，能快速生成完整客户端代码的项目 | 类似swagger-typescript-api |
💡 适用场景
openapi-typescript是一个追求纯粹和极简的工具，非常适合以下情况：
使用 OpenAPI 规范的 TypeScript 项目：它是最核心的应用场景，为项目提供基础类型保障。
追求零运行时开销：如果你只需要类型检查，不希望引入任何无关的运行时代码，它是理想之选。
想要完全控制请求逻辑：相比生成完整客户端代码的工具，
openapi-typescript让你能自由搭配fetch、axios等任何库，拥有最高的灵活性。
总的来说，如果你认同“类型与实现分离”的理念，并希望在项目中获得最高灵活性和最纯粹的 TypeScript 类型体验，openapi-typescript是一个非常合适的选择。