告别手写API类型！手写一款VS Code神器让你的开发效率飞起来

一个由笔者亲手打造的VS Code扩展，专为解决前端API开发痛点而生，支持将多种API文档格式自动转换为TypeScript类型定义和请求代码。

💭 开发者的痛点，我们都懂

作为前端开发者，你是否经历过这样的场景：

• 📝 拿到后端的Swagger文档，需要手动编写TypeScript接口定义
• 🔄 API接口频繁变更，类型定义总是滞后，导致运行时错误
• 😫 多个项目使用不同的API文档格式，需要重复造轮子
• ⏰ 花费大量时间在重复性的代码生成工作上

如果你深有同感，那么今天要介绍的这款VS Code扩展——Swagger Doc To Code，将彻底改变你的开发体验！这是一个完全由开发者自主研发的工具，专门为解决API开发中的实际痛点而设计。

🌟 为什么我要开发这款扩展？

作为一名资深前端开发者，我深知API开发中的各种痛点。市面上虽然有一些解决方案，但要么操作复杂，要么功能单一，要么需要额外的学习成本。于是我决定自己动手，打造一款真正符合开发者使用习惯的工具。

🎯 核心设计理念

• 🎨 一站式可视化管理：告别命令行，拖拽点击即可完成所有操作
• 🚀 智能增强功能：不仅生成代码，还提供智能提示、代码片段等开发辅助
• 🔧 高度可定制化：自动生成模板文件，支持团队个性化定制
• 🧪 API测试集成：内置测试功能，生成即可测试

💪 独家特性

• 🚀 多格式支持：支持Swagger v2、OpenAPI 3.0+、Postman Collection等主流API文档格式
• 📝 智能类型生成：自动生成完整的TypeScript接口定义，包含请求参数和响应类型
• 🎯 命名空间隔离：每个接口生成独立的命名空间，避免类型冲突
• 🔄 增量更新：智能比对变更，仅更新有变化的接口文件
• 🎨 自定义模板：支持自定义代码生成模板，满足不同项目需求
• 🌏 中文转英文：智能中文分组名称转换，确保文件夹命名规范
• 🎉 智能欢迎：首次使用引导和版本升级通知
• 📊 实时统计：状态栏显示API数量和快速操作入口
• 🔍 智能提示：TypeScript文件中的API类型智能补全
• 🧪 API测试：一键生成测试代码和cURL命令
• 📋 批量操作：支持按分组批量复制接口请求代码

🛠️ 安装指南

方法一：VS Code扩展市场搜索安装（推荐）

1. 打开VS Code
2. 点击左侧活动栏的扩展图标（或按Ctrl+Shift+X）
3. 在搜索框中输入：Swagger Doc To Code
4. 找到由niuge666发布的扩展
5. 点击"安装"按钮

方法二：命令行安装

code --install-extension niuge666.swagger-doc-to-code

🎮 快速上手

安装后的界面

安装完成后，你会在VS Code左侧活动栏看到一个小蜜蜂图标，这就是Swagger Doc To Code的入口。

基础配置

1. 配置数据源

在VS Code设置中配置你的API文档源：

{
  "apiDocToTypes.dataSources": [
    {
      "title": "用户服务API",
      "url": "https://api.example.com/swagger.json",
      "type": "swagger",
      "link": "https://api.example.com/docs"
    },
    {
      "title": "订单服务API",
      "url": "./docs/order-api.json",
      "type": "openapi",
      "basePath": "/api/v1"
    }
  ]
}

2. 生成类型文件

• 使用快捷键Alt + Shift + F打开接口列表
• 选择需要的接口并生成TypeScript类型文件
• 生成的文件将保存到配置的目录中

🔄 完整工作流程

🎨 功能亮点详解

1. 🎯 一站式可视化管理

传统方式：文档 → 命令行 → 配置 → 生成 → 手动整理
Swagger Doc To Code：拖拽 → 点击 → 完成 ✨

• 可视化接口树：直观浏览所有API接口
• 一键批量生成：选择需要的接口，批量生成类型文件
• 实时预览：生成前可预览代码结构

2. 🚀 智能增强功能

智能代码提示

// 输入时自动提示可用的API类型
import { UserLogin } from './types/api-interfaces/user-login'

// 鼠标悬停显示详细信息
const params: UserLogin.Params = {
  username: 'admin', // <- 智能提示参数类型
  password: '123456'
}

代码镜头功能

export namespace UserLogin { // <- 显示 [🚀 生成请求函数] [🧪 测试 API] 按钮
  export interface Params {
    username: string
    password: string
  }
}

丰富的代码片段

• api-get + Tab → 生成GET请求函数
• api-post + Tab → 生成POST请求函数
• api-interface + Tab → 生成接口类型定义

3. 🔧 高度可定制化

自动生成模板文件

🎉 独家特性：首次使用时自动生成 .vscode/swagger-doc-to-code.template.js 模板文件

// 自定义命名空间
function namespace(context) {
  const { groupName, pathName, method } = context
  return `${groupName.replace(/[\-\n\s\/\\]/g, '_')}_${pathName}_${method}`
}

// 自定义参数接口
function params(context) {
  return `export interface Params {
${context.properties.map(prop => 
  `  ${prop.name}${prop.required ? '' : '?'}: ${prop.type}`
).join('\n')}
}`
}

4. 🧪 API测试集成

一键生成测试代码

// 自动生成的测试代码
describe('UserLogin API', () => {
  it('should call UserLogin successfully', async () => {
    const params: UserLogin.Params = {
      // TODO: 填写测试参数
    }
    const response = await userlogin(params)
    expect(response).toBeDefined()
  })
})

生成cURL命令

# 一键复制到剪贴板
curl -X POST \
  'https://api.example.com/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "admin",
    "password": "123456"
  }'

🎨 详细功能展示

1. 智能类型生成

扩展会自动解析API文档，生成完整的TypeScript接口定义：

/**
 * 用户登录接口
 * @path /api/auth/login
 * @method POST
 */
export namespace UserLogin {
  export interface Params {
    username: string
    password: string
  }

  export interface Response {
    token: string
    userInfo: {
      id: number
      username: string
      email: string
    }
  }
}

2. 一键复制请求代码

支持生成并复制完整的请求函数代码：

/** 用户登录 */
export async function userLogin(
  params?: UserLogin.Params,
  options?: RequestOptions
) {
  return $api
    .request<UserLogin.Response>('/api/auth/login', params, {
      method: 'POST',
      ...options,
    })
    .then((res) => res.content || {})
}

3. 中文转英文优化

智能处理中文分组名称，确保文件夹命名规范：

用户管理 → user-management
获取用户列表 → get-user-list
创建订单接口 → create-order-interface
数据分析报表 → data-analysis-report

4. 批量操作

• 批量复制：一次性复制整个分组的所有接口请求代码
• 批量更新：检查所有已生成的文件并更新有变化的接口
• 智能增量：仅更新有变化的文件，提高效率

🧪 高级功能

API测试功能

一键生成测试代码和cURL命令：

// 生成的测试代码
describe('UserLogin API', () => {
  it('should call UserLogin successfully', async () => {
    const params: UserLogin.Params = {
      username: 'test',
      password: '123456'
    }

    const response = await userLogin(params)
    expect(response).toBeDefined()
  })
})

# 生成的cURL命令
curl -X POST \
  'https://api.example.com/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "test",
    "password": "123456"
  }'

代码片段系统

内置丰富的代码片段，提高开发效率：

• api-get + Tab：生成GET请求函数
• api-post + Tab：生成POST请求函数
• api-interface + Tab：生成接口类型定义

智能代码提示

在TypeScript文件中享受智能提示：

• 类型导入自动补全
• 悬停显示API详细信息
• 代码镜头快速操作

📊 版本更新亮点

v1.1.2 最新功能

• 🌏 中文转英文优化：引入pinyin-pro库，智能处理中文分组名称转换
• 🔍 智能中文检测：精确识别中文字符
• 📚 分层转换策略：优先使用常用词汇映射，智能拼音转换作为补充
• 🎯 词汇映射扩展：新增大量常用技术词汇的中英文映射表
• 🧹 格式化处理：自动清理特殊字符，确保生成的文件夹名称符合规范

v1.1.0 重大更新

• ✨ 智能欢迎系统：首次使用和版本升级时显示欢迎界面
• 🎯 智能代码提示：TypeScript/JavaScript文件中的API类型智能补全
• 📝 代码片段系统：内置8种API开发代码模板
• 🧪 API测试功能：生成API测试代码和cURL命令
• 📊 状态栏增强：显示API统计信息和快速生成按钮

🔧 配置选项

🎮 快捷键

💡 实际应用场景

场景1：新项目快速启动

// 1. 配置API文档源
// 2. 批量生成所有接口类型
// 3. 使用代码片段快速编写请求函数

// 生成的类型文件
export namespace UserAPI {
  export interface LoginParams {
    username: string
    password: string
  }
  
  export interface LoginResponse {
    token: string
    userInfo: UserInfo
  }
}

// 使用api-post片段生成的请求函数
export async function login(
  data: UserAPI.LoginParams,
  options?: RequestOptions
) {
  return request<UserAPI.LoginResponse>({
    url: "/api/auth/login",
    method: "POST",
    data,
    ...options
  })
}

场景2：API变更快速同步

后端更新API → 点击刷新按钮 → 自动检测变更 → 一键更新类型文件 ✨

场景3：多项目类型管理

• 项目A：电商API
• 项目B：用户中心API
• 项目C：支付API

统一在VS Code中管理，切换项目时自动加载对应的API类型。

🔗 获取扩展

GitHub仓库

• 项目地址：https://github.com/xiaoniuge36/swagger-doc-to-code
• 问题反馈：https://github.com/xiaoniuge36/swagger-doc-to-code/issues
• 功能建议：https://github.com/xiaoniuge36/swagger-doc-to-code/discussions

VS Code市场

• 扩展页面：https://marketplace.visualstudio.com/items?itemName=niuge666.swagger-doc-to-code
• 安装命令：code --install-extension niuge666.swagger-doc-to-code

作者信息

• 邮箱联系：694838286@qq.com

🚀 开始你的高效开发之旅

🎯 三步上手

1. 🔍 搜索安装

   • 打开VS Code扩展市场
   • 搜索"Swagger Doc To Code"
   • 点击安装，立即拥有

2. ⚙️ 简单配置

   {
     "SwaggerDocToCode.swaggerJsonUrl": [
       {
         "title": "我的API服务",
         "url": "https://api.example.com/swagger.json"
       }
     ]
   }
   

3. 🎉 开始创造

   • 按下 Alt + Shift + F 打开接口面板
   • 选择需要的接口
   • 一键生成，立即使用

💡 首次使用小贴士

扩展会自动为你生成模板文件，你可以根据团队需求进行个性化定制。智能欢迎界面会引导你完成初始设置，让你快速上手。

🎉 用户反馈

“以前手写API类型要花半天时间，现在5分钟就搞定了！” - 某大厂前端工程师

“自定义模板功能让我们团队的代码风格完全统一。” - 某大厂技术负责人

🔮 未来规划

• 🔄 GraphQL Schema支持
• 🎨 更多代码生成模板
• 🤖 AI辅助API文档理解
• 📱 移动端API适配
• 🌐 团队协作功能

📝 写在最后

Swagger Doc To Code 不仅仅是一个代码生成工具，更是我作为开发者对于提升开发体验的一次探索和实践。它通过：

• 🎯 降低学习成本：可视化操作，无需命令行
• ⚡ 提升开发效率：智能提示、代码片段、一键生成
• 🔧 增强开发体验：VS Code原生集成，无缝工作流
• 🎨 保证代码质量：自动生成、类型安全、团队规范

让开发者能够专注于业务逻辑，而不是重复性的类型定义工作。

立即体验：在VS Code扩展市场搜索 “Swagger Doc To Code”，开启你的高效API开发之旅！

如果这篇文章对你有帮助，请给项目一个⭐Star，让更多开发者受益！