告别手写文档！我开发了一个自动化 API 文档工具

张海潮
61 阅读5分钟

前言

作为一名前端开发者，你是否也有过这样的痛苦经历：

  • 📝 手写文档太费时：每次对接新接口，都要在文档里复制粘贴，手动整理请求参数和响应结构
  • 🔄 文档更新不及时：接口改了，文档忘记更新，导致团队成员踩坑
  • 💔 类型定义难维护：用 TypeScript 开发，还要手动写一堆 interface，效率极低
  • 🤯 接口越来越多：项目迭代几个月，接口上百个，文档管理混乱不堪

如果你也遇到这些问题，那么这篇文章介绍的工具正是为你而生！

image.png

今天我要分享一个开源项目：API 文档自动化工具 —— 一款基于 Electron + Vue 3 开发的桌面应用，它能够：

✅ 自动收集 Postman 的接口请求和响应

✅ 智能生成 TypeScript 类型定义

✅ 一键导出 Markdown 格式的接口文档

✅ 本地存储，数据安全可靠

一、为什么要做这个工具？

痛点 1：重复劳动太多

在前端开发中，对接后端接口是日常工作的重要一环。传统的工作流程是这样的：

  1. 在 Postman 测试接口
  2. 复制请求参数和响应数据到文档
  3. 手动编写 TypeScript 类型定义
  4. 粘贴到项目代码中

这个过程不仅繁琐，而且容易出错。如果接口改了，你还要重复这个流程。

痛点 2：文档和代码分离

很多团队用 Swagger、YApi 等工具管理接口文档，但这些工具和实际开发流程是脱节的：

  • 后端更新了接口，忘记更新文档
  • 前端在 Postman 测试通过，但文档上还是旧的
  • 文档上说返回字段 A，实际返回的是字段 B

痛点 3：TypeScript 类型定义难写

TypeScript 开发必须定义类型，但手写 interface 真的很累：

// 你需要手动写这么多...
interface LoginRequest {
  username: string
  password: string
  remember: boolean
}

interface LoginResponse {
  code: number
  message: string
  data: {
    userId: number
    token: string
    userInfo: {
      name: string
      avatar: string
    }
  }
}

如果能自动生成，该多好啊！

二、解决方案：自动化 API 文档工具

基于以上痛点，我开发了这款工具。它的核心思路是：在开发过程中自动收集接口信息，无需额外操作。

工作原理

Postman 发起请求
    ↓
全局后置脚本捕获数据
    ↓
通过 HTTP 转发到本地服务
    ↓
Electron 应用接收并存储
    ↓
分析 JSON 结构生成 TS 类型
    ↓
展示在界面 + 支持导出 Markdown

三、核心功能详解

1️⃣ 自动接口收集

只需在 Postman 中配置一次全局后置脚本，之后每次发起请求，接口信息都会自动转发到工具中。

Postman 配置步骤：

进入 Settings → Scripts → Global Scripts → Post-response，添加以下代码：

const requestData = {
  requestName: pm.info.requestName,
  request: {
    url: pm.request.url.toString(),
    method: pm.request.method,
    headers: pm.request.headers.toObject(),
    body: pm.request.body
  },
  response: {
    code: pm.response.code,
    status: pm.response.status,
    body: pm.response.json(),
    headers: pm.response.headers.toObject()
  }
}

pm.sendRequest(
  {
    url: 'http://localhost:3737/api/collect',
    method: 'POST',
    header: { 'Content-Type': 'application/json' },
    body: { mode: 'raw', raw: JSON.stringify(requestData) }
  },
  (err, res) => {
    if (err) console.log('转发失败:', err)
  }
)

配置完成后，Postman 每次发起请求都会自动记录到工具中，完全无感！

2️⃣ TypeScript 类型自动生成

这是我最喜欢的功能！工具会分析请求参数和响应数据的结构，自动生成 TypeScript 类型定义。

示例：

输入（响应数据）：

{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1001,
    "token": "xxxxxx",
    "userInfo": {
      "name": "张三",
      "avatar": "https://..."
    }
  }
}

输出（TypeScript 类型）：

interface LoginResponse {
  code: number
  message: string
  data: LoginResponseData
}

interface LoginResponseData {
  userId: number
  token: string
  userInfo: UserInfo
}

interface UserInfo {
  name: string
  avatar: string
}

再也不用手写啦！直接复制粘贴到代码里就行。

3️⃣ 项目与接口管理

工具支持多项目管理，可以根据 baseUrl 自动分类接口：

  • 🗂️ 项目列表：按项目组织接口，清晰明了
  • 🔍 搜索筛选：支持按接口名称、请求方式、标签筛选
  • 📊 调用统计：记录每个接口的调用次数和最后更新时间
  • ✏️ 手动编辑：可以为接口添加描述、标签等信息

界面预览转存失败，建议直接上传图片文件

4️⃣ Markdown 文档导出

选择要导出的项目和接口，一键生成 Markdown 文档。

支持自定义导出字段：

  • ✅ 接口名称
  • ✅ 请求方式
  • ✅ 请求路径
  • ✅ 请求参数（JSON + TypeScript）
  • ✅ 响应数据（JSON + TypeScript）
  • ✅ 接口描述
  • ✅ 更新时间

导出效果：

## 用户登录

**请求方式：** POST
**请求路径：** `/api/v1/user/login`

### 请求参数

```json

{ "username": "admin", "password": "123456" }


### 请求参数类型

```typescript
interface LoginRequest {
username: string;
password: string;
}

完美！可以直接分享给团队成员或者放到项目 Wiki 里。

image-20251111111214302.pngimage-20251111111311422.png

四、技术实现

技术栈

  • 框架：Electron 38 + Vue 3.5
  • UI 组件库：Arco Design Vue
  • 构建工具：electron-vite
  • 数据库：IndexedDB（Electron内置）
  • HTTP 服务：Express.js
  • 类型生成：参考 json-to-ts

架构设计

项目采用 Electron 的三进程架构：

  1. 主进程（Main Process）

    • 启动 HTTP 服务接收 Postman 数据
    • 处理文件保存（Markdown 导出）
    • 管理系统托盘

  2. 预加载脚本（Preload）

    • 使用 contextBridge 暴露安全 API
    • 连接主进程和渲染进程

  3. 渲染进程（Renderer）

    • Vue 3 单页应用
    • IndexedDB 数据操作
    • 类型生成和 Markdown 生成逻辑

IndexedDB 数据设计

projects 表（项目表）：

interface Project {
  id: string
  name: string
  baseUrl: string
  description?: string
  createdAt: number
  updatedAt: number
}

apis 表（接口表）：

interface ApiRecord {
  id: string
  projectId: string
  name: string
  path: string
  method: string
  requestParams: any
  requestParamsType: string // TS 类型定义
  responseBody: any
  responseType: string // TS 类型定义
  tags?: string[]
  callCount: number
  createdAt: number
  updatedAt: number
}

TypeScript 类型生成算法

核心算法参考 json-to-ts，通过递归分析 JSON 结构：

  1. 基础类型识别：string | number | boolean | null
  2. 数组类型：分析数组元素类型，生成 Type[]
  3. 对象类型：递归分析属性，生成 interface
  4. 嵌套对象：提取为独立的 interface
  5. 类型合并：多次调用同一接口时，合并类型并标记可选属性

源代码

github

⭐ 如果这个项目对你有帮助，请给它一个 Star！ ❤️

avatar
文章
阅读
粉丝