Yapi2Insomnia

将 Yapi 接口文档自动转换为 Insomnia 导入文件的工具。

功能特性

• ✅ 从 Yapi 获取项目所有接口数据
• ✅ 自动转换为 Insomnia 格式（支持 JSON 和 YAML 格式）
• ✅ 保留分类结构（文件夹）和正确排序
• ✅ 支持请求头、请求参数、请求体
• ✅ 支持 JSON、Form、Raw 类型请求
• ✅ 保留接口描述、Markdown 文档和更新时间
• ✅ 增量更新模式（仅新增接口，保留已有接口）
• ✅ 智能合并（保留用户在 Insomnia 中填写的参数值）
• ✅ 支持读取已有 Insomnia 文件进行增量更新
• ✅ 环境变量管理（自动提取公共请求头）
• ✅ 支持分页获取大量接口

使用方法

1. 配置文件

创建 config.json 文件：

{
  "yapi_base_url": "https://your-yapi-domain.com",
  "yapi_token": "your_yapi_token",
  "yapi_uid": "your_yapi_uid",
  "project_id": 1454,
  "output_file": "insomnia_export.json",
  "insomnia_file": "existing_insomnia.yaml",
  "incremental": false
}

配置字段说明：

• yapi_base_url: Yapi 服务地址
• yapi_token: Yapi 认证 Token
• yapi_uid: Yapi 用户 ID
• project_id: Yapi 项目 ID
• output_file: 输出文件路径（支持 .json 和 .yaml 格式）
• insomnia_file: 已有的 Insomnia 文件路径（可选，用于增量更新）
• incremental: 是否启用增量模式（仅新增接口，不更新已有接口）

获取 Token 的方法：

1. 登录 Yapi
2. 打开浏览器开发者工具 (F12)
3. 切换到 Network 标签
4. 刷新页面
5. 查看任意请求的 Cookie，找到 _yapi_token 和 _yapi_uid

2. 运行程序

# 编译
go build -o yapi2insomnia

# 基本使用
./yapi2insomnia -config config.json

# 启用增量模式（仅新增接口）
./yapi2insomnia -config config.json -incremental

# 使用 YAML 配置文件
./yapi2insomnia -config config.yaml

命令行参数：

• -config: 配置文件路径（默认：config.json）
• -incremental: 启用增量模式（仅新增接口，优先级高于配置文件）

3. 导入 Insomnia

1. 打开 Insomnia
2. 点击 Application -> Preferences -> Data -> Import Data
3. 选择生成的导出文件（JSON 或 YAML 格式）
4. 导入完成！

4. 增量更新模式

增量更新模式允许你在不丢失现有工作的情况下添加新接口：

# 方式1：配置文件设置
{
  "incremental": true,
  "insomnia_file": "existing_insomnia.yaml"
}

# 方式2：命令行参数
./yapi2insomnia -config config.json -incremental

增量模式特点：

• 仅添加 Yapi 中存在但 Insomnia 文件中不存在的新接口
• 保留所有已有接口、文件夹结构和用户填写的参数值
• 不会修改或删除任何已有接口
• 支持智能合并，保留用户在 Insomnia 中的修改

项目结构

.
├── main.go           # 主程序
├── config.json       # 配置文件（需自行创建）
├── config.yaml       # YAML 格式配置文件（可选）
├── go.mod            # Go 模块文件
├── go.sum            # Go 依赖校验文件
└── README.md         # 说明文档

配置说明

字段	说明	必填	默认值
yapi_base_url	Yapi 服务地址	✅	-
yapi_token	Yapi 认证 Token	✅	-
yapi_uid	Yapi 用户 ID	✅	-
project_id	Yapi 项目 ID	✅	-
output_file	输出文件路径	❌	insomnia_export_{timestamp}.json
insomnia_file	已有 Insomnia 文件路径（用于增量更新）	❌	-
incremental	是否启用增量模式	❌	false

技术实现

• 语言: Go 1.21+
• 依赖库:
  • gopkg.in/yaml.v3 - YAML 解析支持
• API 格式: Insomnia Export Format v4
• 支持的请求类型: JSON、Form、Raw
• 输出格式: JSON、YAML（根据文件扩展名自动判断）

注意事项

1. Token 管理: Token 有过期时间，需要定期更新
2. 网络环境: 需要在公司内网环境运行（如果 Yapi 是内网服务）
3. 性能优化: 接口数量较多时，获取详情会需要一些时间，程序会自动添加请求延迟避免过快
4. 文件格式: 输出文件格式根据扩展名自动判断（.json/.yaml/.yml）
5. 增量更新: 建议在已有工作基础上使用增量模式，避免重复劳动
6. 环境变量: 程序会自动将公共请求头转换为环境变量，便于统一管理
7. 用户修改保护: 增量模式下会保留用户在 Insomnia 中填写的参数值和禁用状态

高级用法

YAML 配置文件

除了 JSON 格式，也支持 YAML 格式的配置文件：

yapi_base_url: "https://your-yapi-domain.com"
yapi_token: "your_yapi_token"
yapi_uid: "your_yapi_uid"
project_id: 1454
output_file: "insomnia_export.yaml"
insomnia_file: "existing_insomnia.yaml"
incremental: true

智能合并策略

当使用增量更新时，程序会：

1. 保留用户修改: 保留用户在 Insomnia 中手动修改的参数值
2. 保留禁用状态: 保留用户手动禁用的参数状态
3. 保留新增接口: 保留用户在 Insomnia 中手动添加的接口
4. 更新接口信息: 更新接口标题、描述等基本信息
5. 合并环境变量: 保留用户添加的环境变量

输出示例

程序运行时会显示详细的执行过程：

🚀 Yapi2Insomnia 开始运行...
📋 项目ID: 1454
🔄 增量模式已启用：将仅新增接口，保留已有接口
📦 获取项目详情...
✅ 项目名称: API文档项目
✅ 成功获取 12 个分类
📡 获取接口列表...
✅ 成功获取 156 个接口
📥 读取已有的 Insomnia 文件: existing_insomnia.yaml
✅ 成功读取 Insomnia 文件
📊 已存在 120 个接口
🔄 增量模式：跳过 120 个已存在接口，需获取 36 个新接口详情
🔍 开始获取接口详情...
  [1/36] GET 用户详情接口
  [2/36] POST 创建用户接口
  ...
✅ 成功获取 36 个接口详情
📁 获取分类列表...
✅ 成功获取 12 个分类（已按正确顺序排列）
🔄 转换为 Insomnia 格式...
🔄 增量模式：保留所有已有接口，添加新接口...

✅ 导出成功！
📄 文件: insomnia_export.yaml
📊 统计: 156 个接口, 12 个分类

💡 请使用 Insomnia 的 Import 功能导入此文件

License

MIT

贡献指南

欢迎提交 Issue 和 Pull Request！在提交代码前，请确保：

1. 代码通过基本测试
2. 更新相关文档
3. 遵循 Go 代码规范

更新日志

v1.1.0

• ✅ 新增增量更新模式
• ✅ 支持 YAML 格式输出
• ✅ 智能合并用户修改
• ✅ 环境变量自动管理
• ✅ 支持分页获取大量接口
• ✅ 改进错误处理和日志输出

v1.0.0

• ✅ 基础功能实现
• ✅ 支持 JSON 格式输出
• ✅ 保留分类结构
• ✅ 支持多种请求类型