Swagger TypeScript 类型生成器 MCP

一个强大的MCP（Model Context Protocol）工具，用于从Swagger接口文档自动生成TypeScript类型定义。

功能特性

• 🚀 智能解析：自动解析Swagger接口文档，提取参数和响应类型
• 📝 双输出模式：支持控制台输出（复制模式）+ 文件保存模式
• 🔄 批量生成：支持单个接口和分类批量生成
• 🎯 Cursor集成：支持Cursor IDE智能调用 + 命令行直接使用
• 📦 类型安全：生成完整的TypeScript接口定义，包含注释和类型约束

安装

npm install
npm run build

使用方法

1. MCP模式（Cursor IDE集成）

在Cursor IDE中，您可以直接调用以下工具：

生成单个接口类型

@generate_types_from_swagger
swaggerUrl: "https://pref-erp-gateway.cht-group.net/doc.html#/oms-service/refresh-cache-controller/refreshCacheByKeyUsingPOST"
outputMode: "both"
outputPath: "./types.ts"
includeComments: true

批量生成多个接口类型

@generate_batch_types
swaggerUrl: "https://pref-erp-gateway.cht-group.net/oms-service/v2/api-docs"
operationIds: ["refreshCacheByKeyUsingPOST", "healthUsingGET"]
outputMode: "both"
outputPath: "./batch-types.ts"
includeComments: true

2. 命令行模式

生成单个接口类型

# 控制台输出
npx swagger-ts-gen generate "https://pref-erp-gateway.cht-group.net/doc.html#/oms-service/refresh-cache-controller/refreshCacheByKeyUsingPOST" --mode console

# 保存到文件
npx swagger-ts-gen generate "https://pref-erp-gateway.cht-group.net/doc.html#/oms-service/refresh-cache-controller/refreshCacheByKeyUsingPOST" --output ./types.ts --mode file

# 双模式（控制台输出 + 文件保存）
npx swagger-ts-gen generate "https://pref-erp-gateway.cht-group.net/doc.html#/oms-service/refresh-cache-controller/refreshCacheByKeyUsingPOST" --output ./types.ts --mode both

批量生成多个接口类型

npx swagger-ts-gen batch "https://pref-erp-gateway.cht-group.net/oms-service/v2/api-docs" \
  "refreshCacheByKeyUsingPOST" \
  "healthUsingGET" \
  --output ./batch-types.ts --mode both

从本地文件生成

npx swagger-ts-gen from-file ./swagger.json "batchSubmitDomesticDirectShipmentUsingPOST" --output ./types.ts

工作原理

URL解析流程

1. 解析用户提供的Swagger接口URL
2. 提取基础URL（如：https://test-ytoms-api.cht-group.net/oms-pref/）
3. 提取服务路径（如：/oms-service）
4. 构建API文档URL（如：https://test-ytoms-api.cht-group.net/oms-pref/oms-service/v2/api-docs）

类型解析流程

1. 发送GET请求获取Swagger JSON文档
2. 根据operationId查找目标接口定义
3. 递归解析parameters和responses的类型定义
4. 将Swagger类型映射为TypeScript类型
5. 生成完整的接口定义

类型映射规则

• string → string
• integer/number → number
• boolean → boolean
• array → Type[]
• object → interface 或 Record<string, any>
• 引用类型 → 递归解析并生成对应接口

输出示例

生成的TypeScript类型定义示例：

// 自动生成的TypeScript类型定义
// 生成时间: 2024-01-01T00:00:00.000Z

/**
 * 批量提交-国内直发
 */
export interface BatchSubmitDomesticDirectShipmentUsingPOSTRequest {
  list: ShippingOrderDispatchSubmitCmd[];
}

export interface ShippingOrderDispatchSubmitCmd {
  id: number;
  version: number;
  shippingOrderDispatchSubmitDaiMaiCmd?: ShippingOrderDispatchSubmitDaiMaiCmd;
  shippingOrderDispatchSubmitDaiMaiPaByHandCmd?: ShippingOrderDispatchSubmitDaiMaiPaByHandCmd;
  shippingOrderDispatchSubmitDeWmsCmd?: ShippingOrderDispatchSubmitDeWmsCmd;
}

export interface ShippingOrderDispatchSubmitDaiMaiCmd {
  detailList: ShippingOrderDispatchSubmitDetailDaiMaiCmd[];
}

export interface ShippingOrderDispatchSubmitDetailDaiMaiCmd {
  // ... 更多属性
}

export interface BatchSubmitDomesticDirectShipmentUsingPOSTResponse {
  success: boolean;
  message: string;
  data: ShippingOrderDispatchBatchSubmitVO;
}

export interface ShippingOrderDispatchBatchSubmitVO {
  failCnt: number;
  failList: ShippingOrderDispatchSubmitBaseVO[];
  successCnt: number;
  successList: ShippingOrderDispatchSubmitBaseVO[];
}

配置选项

输出模式

• console: 仅在控制台输出
• file: 仅保存到文件
• both: 控制台输出 + 文件保存

命令行选项

• -o, --output <path>: 输出文件路径
• -m, --mode <mode>: 输出模式
• --no-comments: 不包含注释

开发

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 运行
npm start

许可证

MIT License