apidog-import-export

导入、导出与质量门禁

前置条件：先阅读 ../apidog-cli/SKILL.md。如果稳定版入口技能与此领域技能冲突，请以当前 CLI 帮助和此技能为准。

始终使用当前 CLI 帮助确认准确参数。导入前，检查文件格式、OpenAPI 质量门禁、路由骨架风险、标签分组、原生格式模块策略、ignoreCount，以及是否需要干净的验证项目。导入后，Agent 必须通过 agentHints、list/get 以及（适用时）run/report 验证结果。不能仅凭导入命令返回成功就认为任务已完成。

适用场景

• 根据代码、PRD、需求文档、测试文档或讨论生成 API 规范，并导入 Apidog。
• 导入 OpenAPI、Postman、HAR、Apidog 原生格式或其他项目数据。
• 配置自动导入。
• 导出 OpenAPI、Markdown、HTML、Postman 或 Apidog 原生格式。
• 判断生成的规范是否只是路由骨架。
• 迁移、备份或复制 Apidog 项目，尤其是在需要控制模块复用或新建模块时。

不适用场景

• 将现有端点、测试用例或场景步骤导入或复制到测试场景：使用 apidog-test-scenario 的 test-scenario import-steps 或 test-scenario add-ref。
• 精确维护场景步骤、变量、断言或处理器：使用 apidog-test-scenario。

命令入口

使用当前 CLI 帮助查看 import、import auto-import、export 和 export settings。导入前不要跳过以下质量门禁。

核心原则

1. 编写提取脚本前，先搜索项目中是否已有生成器。
2. 不要把完整路径误认为完整的 API 规范。
3. 导入前输出质量指标。
4. 同时验证完整性和可读性。
5. 如果导入策略不确定，应先在临时项目或修订后的项目中验证，而不是污染现有项目。
6. 导入结果中的较大 ignoreCount 值是风险信号，而非普通成功。
7. OpenAPI 的 Apidog 文件夹分组取决于操作标签。
8. 不要假设文件扩展名就代表实际格式。

标准流程

步骤 0：确定任务类型

首先判断用户要求的任务类型：

任务	下一步
从代码、PRD 或文档生成规范并导入	继续步骤 1
直接导入现有文件	从步骤 3 开始
配置自动导入	阅读当前 CLI 帮助和 schema，然后创建配置
导出文档或 OpenAPI	直接使用导出功能，然后确认文件已生成
迁移或备份 Apidog 项目	使用 Apidog 原生格式导出/导入，并确认模块导入策略
将现有资源导入测试场景	切换到 apidog-test-scenario；不要使用 OpenAPI 导入

如果用户未指定目标项目、团队、导入策略，或是否允许创建新项目，请在安全的情况下根据上下文推断。如果不确定，只询问一个必要的最简问题。

步骤 1：搜索现有生成器

对于根据源代码、文档、PRD 或测试生成 API 规范、文档或类型的请求，首先搜索项目中是否已有生成器：

openapi
swagger
routegen
route-gen
docs generator
api docs
schema generator
cmd/openapi
cmd/*openapi*

正确做法：

• 先运行项目自身的生成器。
• 优先使用能够提取处理器请求/响应结构体、DTO 和 schema 的工具。
• 不要一开始就手动解析路由文件；这样通常只会生成方法 + 路径骨架。

如果没有生成器，可以考虑根据框架路由、注释、DTO、schema、测试或文档生成。仍需继续执行步骤 3 及后续质量门禁。

第 2 步：生成规范并确认格式

• 运行项目生成器或官方命令。
• 保存原始产物；不要直接覆盖用户拥有的文件。
• 不要根据扩展名判断格式。
• 读取生成的文件前，先检查文件开头，或使用支持 JSON/YAML 的工具解析。
• 生成器可能会将 YAML 写入 .json 文件；如果出现这种情况，请将其重命名为 .yaml，或按 YAML 解析。

第 3 步：收集导入前指标

导入前，解析生成的 OpenAPI 文件并报告实际指标。不要使用示例值、默认值或占位值。

必需指标：

指标	含义	用途
paths	OpenAPI 路径数量	估算 API 规模
operations	实际操作数量	估算导入规模
schemas	components.schemas 的数量	估算模型完整度
writes	POST/PUT/PATCH 等写入 API	请求体覆盖目标
withBody	带有 requestBody 的写入 API	请求体覆盖情况
emptyObjectBodies	请求体 schema 为空对象	路由骨架风险

以表格或 JSON 的形式输出当前文件的实际统计数据。每个值都必须来自对文件的解析。

第 4 步：判断规范完整度

• 不要使用固定的 schema 数量作为质量门槛。
• 小型、纯 GET、健康检查、Webhook 透传或非 JSON 请求体项目，即使 schemas=0/1，也可能符合要求。
• API 和写入操作很多、但 schema 极少的大型项目，很可能只是路由骨架。
• 许多 POST/PUT/PATCH 请求体缺失或表示为 {}，是强烈的风险信号。
• 仅有方法 + 路径，并不能证明 requestBody、响应或 schema 完整。

风险信号：

• 操作很多，但 schema 几乎没有。
• 写入 API 缺少 requestBody。
• 请求体为空对象。
• 响应只有通用字符串或空对象。
• 缺少标签或标签过于宽泛，导致文件夹分组效果不佳。

风险较高时，请说明风险，并建议在导入前完善生成器或源注解，或先导入临时项目进行可视化验证。

第 5 步：导入

使用当前 CLI 帮助信息确认确切的格式和参数。命令形式示例：

apidog import --project <projectId> --format openapi --file <openapiFile>
apidog import --project <projectId> --format postman --file <postmanFile>
apidog import --project <projectId> --format apidog --file <nativeFile> --module-import-mode match-name

对于原生 Apidog 项目文件，请慎重选择模块策略：

• 默认的 match-name：仅当源模块名称唯一匹配一个目标模块时才复用该目标模块；否则创建新模块。
• new：为未被 --module-map 覆盖的源模块创建新模块。
• --module-map：将源模块显式映射到目标模块 ID、default 或 new。

建议在 --module-map 中使用目标模块 ID，以避免同名歧义。

第 6 步：验证导入结果

导入后，不要只检查成功标志，还要验证：

• 检查 success 和退出代码。
• 查看已导入数量、忽略数量和警告。
• 使用 endpoint list、schema list、文件夹/模块视图或相关命令确认资源可见。
• 确认 API 已进入预期的模块/文件夹。
• 如果导入的是测试资源，请通过相应领域命令验证测试用例、场景、套件和类别。
• 如果客户端显示效果很重要，请打开相同的项目/分支/模块/类别上下文，或使用 CLI 回读确认确切位置。

如果 ignoreCount 较高或资源缺失，不要盲目重复相同的导入操作。请先诊断格式、模块策略、不支持的资源类型和警告详情。

导出规则

使用当前 CLI 帮助信息确认支持的格式和选项。导出后：

• 确认输出文件存在。
• 检查文件是否为预期的有效 JSON/YAML/Markdown/HTML。
• 对于 OpenAPI 导出，确认是否需要扩展属性。
• 对于原生导出，将其用于迁移/备份，并配合明确的导入策略。

命令形式示例：

apidog export --project <projectId> --format openapi --output <file>
apidog export --project <projectId> --format markdown --output <file>
apidog export --project <projectId> --format apidog --output <file>

常见故障恢复

症状	操作
导入成功，但缺少 API	检查警告、ignoreCount、模块策略以及 list/get 结果
API 分组不合理	检查 OpenAPI 操作标签
生成的规范只有路径	查找更合适的生成器，或完善 DTO/架构提取
原生导入创建了重复模块	谨慎使用 --module-map 或 --module-import-mode match-name
导出文件无法使用	确认格式、输出路径，以及文件是否为预期的 JSON/YAML/HTML/Markdown