前端对接十几个微服务，每个 Swagger 文档都因 CORS 打不开；为了看一眼接口定义，不得不启动几百 MB 的 Postman；后端悄悄改了字段类型，联调报错才发现代码白写了——这些碎片化的痛点，正在割裂你的工作流。
ApiPreview 就是为解决这些”最后一公里”难题而生的。基于 Electron 33 与 Vue 3.5 打造的桌面阅读器，主进程直连绕过 CORS，Schema 驱动的智能表单让调试可视化，内置 Diff 引擎主动感知 API 变更。轻量、本地、安全，开箱即用。
🖥️ 先看全貌
深色优先的专业 API 工作台。三栏布局：工作区 → API 列表 → 详情面板，信息密度高，操作路径短。
① 内网文档无障碍加载与多源聚合
浏览器访问内网 Swagger，CORS 错误几乎是必经之路。ApiPreview 利用 Electron 主进程直接发起网络请求，从根本上规避跨域限制——无论目标服务器是否配置了 Access-Control-Allow-Origin，只要网络可达，文档即可加载。
微服务架构下，单文档视图捉襟见肘。ApiPreview 支持多源聚合管理：同时加载订单服务、用户服务、支付服务等十几个微服务的 OpenAPI 定义，系统自动将分散的文档聚合在左侧 Tag 侧栏中，按业务模块逻辑分组。
这种聚合基于加权搜索的深度整合。搜索关键词（如 userId）时，引擎同时检索 path（权重 5）、summary（权重 3）与 tag（权重 2），结果 HTML 高亮显示，按相关度排序。无论接口隐藏在哪个微服务下，都能一键定位。
一个窗口掌控整个系统的接口脉络，无需在十几个浏览器标签页之间反复切换。
② Schema 驱动的智能表单调试
传统 API 调试要求手动构造 JSON Body，面对深层嵌套对象或复杂数组时，记忆字段结构极为痛苦。ApiPreview 将 OpenAPI Schema 直接转化为可交互的智能表单（SmartForm）：
- 对象类型 → 嵌套键值对编辑器
- 枚举类型 → 下拉选择框
- 布尔值 → 开关控件
- 数组类型 → 可增删的子项列表
- 必填字段 → 明确的视觉提示
表单底层的 FormField 结构与 OpenAPI Schema 一一对应，支持 format（date-time、email、uuid 等）、enum、嵌套 object/array，以及 oneOf/allOf 等复合结构。你只需像填写网页表单一样填入数据，系统自动将其序列化为标准 JSON Payload。
同时内置 JSON 编辑器支持实时语法校验，配合全局 Bearer Token 的一次性配置，所有后续请求自动注入认证信息。所有请求经 Electron 主进程转发，完全无 CORS 限制。
③ API 变更差异检测与影响分析
接口文档滞后更新是引发线上故障的常见原因。ApiPreview 内置 Diff 引擎，每次重新拉取文档时自动与本地缓存的上一版本快照进行比对。
| 对比维度 | 展示内容 |
|---|---|
| API 级别 | 新增 / 删除 / 变更的接口列表 |
| Schema 级别 | DTO 字段增删、类型变化、required 变更逐项展示 |
| 影响分析 | Schema 变更 → 自动标记受影响的 API（Impacted 徽标） |
modified 项可展开查看 old → new 字段级细节，类型变更与 required 变更一目了然：
当检测到某个基础 Schema 发生变更时，系统基于 $ref 引用图计算传递闭包，自动标记所有直接或间接引用了该 Schema 的 API 接口，在 Diff 面板的 Schema 标签页中以 “Impacted” 徽标提示：
在 API 列表中，受影响的接口同样会显示 “Impacted” 徽标，让你在浏览时也能第一时间感知风险：
快照历史每个源保留最近 10 份，自动清理最旧记录，零维护成本。Diff 默认对比「最新历史 vs 当前拉取结果」。
④ AI 代码生成上下文一键导出
如何向 AI 提供高质量上下文，是提升代码生成准确率的关键。ApiPreview 提供专为 AI Agent 优化的结构化上下文导出：
在导出对话框中，API 按 Tag 分组展示，支持：
- 按 Tag 批量勾选：点击 Tag 标题即可全选/取消该分组下所有接口
- 全选 / 清空：一键操作所有接口
- 展开 / 折叠：按 Tag 分组浏览
导出支持两种格式：
| 格式 | 内容 | 适用场景 |
|---|---|---|
| Markdown | URL、参数表格、请求/响应 Schema 描述、TypeScript 类型定义、JSON 示例 | 直接粘贴到 Chat 窗口，人类可读性强 |
| JSON | 完整 OpenAPI 片段，含 TypeScript 类型映射 | 程序化处理或作为 System Prompt 传入 |
使用经过清洗和结构化的上下文，AI 生成的 Fetch/Axios 调用代码、Mock 数据及单元测试用例准确率显著提升。
⑤ 极致轻量化架构与渲染性能
许多开发工具启动慢、占用内存高。ApiPreview 坚持轻量化设计：渲染层（HTML + CSS + JS）经 Vite 生产构建与 Tree-shaking 优化后，Gzip 压缩体积不到 100 KB，实现秒级启动。
技术栈选择同样体现对性能的极致追求：
| 层级 | 技术 | 为什么选它 |
|---|---|---|
| 桌面框架 | Electron 33 | 主进程直发请求绕过 CORS，沙箱安全隔离 |
| 前端框架 | Vue 3 Composition API | <script setup> 极简语法，Composables 复用逻辑 |
| 语言 | TypeScript 5.7 严格模式 | 零 any 泄漏，全量类型安全 |
| 样式 | Tailwind CSS 3.4 | 深色优先设计系统，CSS Token 驱动，按需加载 |
| 构建 | Vite 6 | 秒级 HMR，双进程构建 |
| 测试 | Vitest 4 | 纯逻辑层单测，core/ 零副作用 |
| 打包 | electron-builder | NSIS 安装包，支持自动更新 |
分层架构进一步保障性能与维护性的平衡：
┌──────────────────────────────────────────┐ |
设计哲学：轻量、分层、不引入重平台抽象。每个模块职责单一，方便阅读和二次开发。
⑥ 企业级安全隔离与隐私承诺
涉及内部接口文档的工具，安全性是不容逾越的红线。ApiPreview 严格执行 Electron 安全最佳实践：
- ✅
contextIsolation: true— 渲染进程无法直接访问 Node.js，防止 XSS 升级为 RCE - ✅
nodeIntegration: false— 禁用 Node 集成，切断恶意脚本利用 Node 环境的路径 - ✅
sandbox: true— 沙箱模式，渲染进程运行在最小权限环境中 - ✅ 导航拦截 — 阻止跳转外部页面，外链交由系统浏览器打开
- ✅ 协议白名单 — 主进程仅允许
http:/https:请求，阻止本地文件或危险协议访问 - ✅ 不收集任何遥测数据，完全离线运行 — 所有文档快照、历史记录均存储在本地
⑦ 深色优先交互设计与聚焦工作流
长时间面对屏幕，护眼至关重要。ApiPreview 采用”深色优先”设计语言，默认主题色彩对比度适中，突出关键信息的同时减轻低光环境下的视觉疲劳。一键切换浅色模式或跟随系统设置，两套主题精心打磨。
界面采用可折叠三栏布局，左侧工作区、中间 API 列表、右侧详情面板均支持独立折叠为窄轨道。需要仔细阅读接口定义或调试参数时，折叠其他区域最大化详情面板空间。
“聚焦当前任务”的交互设计，有效屏蔽无关信息干扰，让心流状态不被打断。
⑧ 典型开发痛点 → 解决方案
| 痛点场景 | 问题 | ApiPreview 解法 |
|---|---|---|
| 🔒 内网联调受阻 | 浏览器报 CORS 错误，无法查看内网 Swagger | Electron 主进程直连，无视跨域限制 |
| 🔗 微服务文档分散 | 十几个服务对应十几个浏览器标签 | 多源聚合展示，统一搜索入口，Tag 分组管理 |
| 🔄 接口变更不知情 | 后端改字段未通知，前端运行时报错 | 自动 Diff 检测 + 影响分析，变被动为主动 |
| 🤖 AI 编程上下文缺失 | 给 AI 的描述模糊，生成代码不可用 | 一键导出结构化 Markdown/JSON 上下文 |
| 🐘 工具过于笨重 | 只为看文档却要启动几百 MB 的客户端 | 百 KB 级渲染体积，秒级启动，用完即走 |
与常见工具的定位对比
| 能力 | ApiPreview | Swagger UI | Postman / Apifox |
|---|---|---|---|
| CORS 绕过 | ✅ 主进程直连 | ❌ 浏览器限制 | ✅ 桌面客户端 |
| 多源聚合 | ✅ 一个窗口管理所有服务 | ❌ 单文档 | ⚠️ 需创建 Workspace |
| API Diff | ✅ 自动检测 + 影响分析 | ❌ | ⚠️ 需手动配置 |
| AI 上下文导出 | ✅ 内置 | ❌ | ❌ |
| 启动体积 | < 100 KB 渲染层 | 浏览器标签 | 数百 MB |
| 离线运行 | ✅ 完全离线 | ❌ 需网络 | ⚠️ 部分功能需联网 |
| 集合/自动化测试 | ❌ | ❌ | ✅ |
ApiPreview 不取代 Postman 或 Apifox 等全能型平台，而是填补”轻量级阅读与快速调试”这一细分领域的空白。
🏁 30 秒快速上手
方式一：直接下载安装包（推荐）
👉 前往 GitHub Release 下载最新版本 — Windows NSIS 安装包，安装后即可使用，无需配置开发环境。
方式二：从源码构建
# 克隆仓库 |
环境要求：Node.js ≥ 18 · npm ≥ 9 · Windows（macOS / Linux 可自行配置 electron-builder target）
启动后：
- 在地址栏粘贴内网 Swagger URL → 文档即刻加载
- 点击「加载示例」→ 体验内置 Petstore 文档
- 选中任意接口 → 切换「调试」标签 → 填表发送请求
- 点击导出按钮 → 勾选 API → 生成 AI 上下文
📄 许可证
MIT License — 自由使用、修改、分发。
👤 作者
Yuxay · GitHub
ApiPreview — 开发者自己的 API 工作台。轻量、本地、安全、开箱即用。