SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场apifox-import-export

apifox-import-export

部署与运维

查看项目

更新于 10-15 12:09

技能介绍

用途

apifox-import-export 是 Apifox CLI 技能集中的一个导入导出与质量门禁技能，用于处理 API spec 与项目数据的导入、导出、迁移、备份和复制。使用前需先阅读 ../apifox-cli/SKILL.md；若旧总入口与本技能的领域规则冲突，以当前 CLI help 和本技能为准。

主要能力

导入

  • 从代码库、PRD、需求文档、测试文档、讨论记录生成 API spec 并导入 Apifox。
  • 导入 OpenAPI、Postman、HAR、Apifox 原生格式等项目数据。
  • 配置自动导入。

导出

  • 导出 OpenAPI、Markdown、HTML、Postman 或 Apifox 原生格式。
  • 原生格式支持全量导出，也支持按接口、目录或标签范围导出，并可控制是否包含接口调试与单接口用例。

质量门禁

  • 导入前校验文件格式、OpenAPI 质量门禁、路由骨架风险、tags 分组、原生格式模块策略、ignoreCount 以及是否需要干净项目验证。
  • 必须实际解析生成的 OpenAPI 文件并报告真实统计值，统计指标包括 paths、operations、schemas、writes、withBody、emptyObjectBodies。
  • 判断 spec 是否为"路由骨架"：接口规模大、写接口多但 schemas 极少属疑似路由骨架；写接口很多但 withBody 覆盖不足、emptyObjectBodies 很多属强风险。小型、纯 GET、健康检查、webhook 透传项目 schemas 少可能合理。
  • 校验 tags 与文档可读性，检查 operation 是否有业务化 tags、tags 是否按业务域分组，不推荐按 URL path 机械分组。

使用方式

标准流程

  1. 明确任务类型（生成 spec 并导入 / 直接导入已有文件 / 配置自动导入 / 导出文档或 OpenAPI / 迁移备份 / 把已有资源导入测试场景）。
  2. 搜索项目内已有生成器（openapi、swagger、routegen、docs generator、cmd/openapi 等），优先运行项目自带生成器，避免手写脚本只提取 method + path 骨架。
  3. 生成 spec 并确认文件格式，不要根据扩展名判断格式。
  4. 导入前统计质量指标并输出真实统计结果。
  5. 判断 spec 完整性。
  6. 校验 tags 和文档可读性。
  7. 选择导入项目，不确定时优先创建临时/修正版项目验证。
  8. 执行导入并检查结果计数，不只依赖命令成功。
  9. 回读验证并汇报，包含文件路径、质量指标或导出范围、导入项目、导入计数、抽查结果和遗留风险。

原生格式导入策略

apifox import --project <projectId> --format apifox --file ./project.apifox.json
apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode match-name
apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode new
apifox import --project <projectId> --format apifox --file ./project.apifox.json \
  --module-map "商店 API=8049476" \
  --module-map "管理 API=8049482"

默认模块策略为 match-name。--module-map 可重复传，优先级高于 --module-import-mode，写法包括"源模块名=目标模块ID""source:源模块ID=目标模块ID""源模块名=default""源模块名=new"。

原生格式导出策略

apifox export --project <projectId> --format apifox --output ./project.apifox.json
apifox export --project <projectId> --format apifox --scope apis --api-ids 1001,1002 --output ./selected.apifox.json
apifox export --project <projectId> --format apifox --scope folders --folder-ids 2001 --output ./folder.apifox.json
apifox export --project <projectId> --format apifox --scope tags --include-tags pet,store --exclude-tags deprecated --output ./tagged.apifox.json
apifox export --project <projectId> --format apifox --no-include-api-cases --output ./apis-only.apifox.json

具体命令参数以当前 CLI help 为准。

适用场景

  • 从代码库、PRD、需求文档、测试文档、讨论记录生成 API spec 并导入 Apifox。
  • 导入 OpenAPI、Postman、HAR、Apifox 原生格式等项目数据。
  • 迁移、备份或复制 Apifox 项目，尤其是需要控制模块复用或新建时。
  • 导出 OpenAPI、Markdown、HTML、Postman 或 Apifox 原生格式。
  • 判断生成的 spec 是否只是"路由骨架"。

限制与不应使用的情况

  • 把已有 endpoint、test-case 或 test-scenario step 导入/复制到测试场景时，应转 apifox-test-scenario，使用 test-scenario import-steps 或 test-scenario add-ref。
  • 精细维护测试场景步骤、变量、断言或处理器时，应转 apifox-test-scenario。
  • 不得先手写路由提取脚本、不得把接口数量多等同于 spec 完整、不得跳过导入前质量指标、不得在已有项目上反复试错导入、不得忽略大量 ignoreCount、不得导入 tags 混乱的 spec 作为最终成果、不得把 schema 极少的大项目 spec 当成最终版本。
  • 如生成器产物 tags 明显过粗或机械来自技术路径（api、v1、rest、service、controller 等），必须停在导入前询问用户是否允许生成修正版 spec。

常见恢复

  • 导入成功但只有路径：回查生成器是否只抽路由，继续找 DTO/handler schema。
  • schemas 极少：结合 operations/writes/withBody/emptyObjectBodies 判断是否路由骨架。
  • 大量空 body：回查 request DTO 或项目生成器。
  • Apifox 目录按 URL 分组：重写 operation tags 后重新导入到干净项目。
  • 大量 ignoreCount：判断是否污染已有项目，必要时新建干净项目验证。
  • JSON.parse 失败：检查实际是否 YAML，不要信扩展名。
  • 原生格式二次导入出现重复模块：检查是否使用默认 match-name、目标同名模块是否唯一，必要时用 --module-map。
  • 目标项目有多个同名模块：不要依赖 CLI 自动猜，使用 --module-map "源模块名=目标模块ID"。