apifox-workflow-api-lifecycle

API 生命周期工作流

开始前必须读取 ../apifox-cli/SKILL.md。若旧总入口与本 workflow 的领域规则冲突，以当前 CLI help 和本 workflow 为准。按步骤再读取 apifox-branch、apifox-import-export、apifox-test-case；涉及复杂测试流程时读取 apifox-test-scenario，涉及执行和 CI 时读取 apifox-test-automation。

具体 endpoint、schema、environment、test-report 命令以当前 CLI help 为准。本流程用于从需求到 API 资产、测试、报告和分支合并的端到端交付，重点关注资源顺序、质量门禁和交付验证。Agent 执行时优先形成 help/schema -> get -> validate -> write -> run/report 闭环，不要仅凭旧文档或记忆写入。

适用场景

• 根据需求创建或更新一组接口。
• 导入 OpenAPI/Postman 后整理接口、Schema、目录和测试。
• 从代码库、PRD、需求文档、测试文档或讨论内容生成 API spec 后导入 Apifox。
• 给接口补 Mock、测试用例、文档和发布设置。
• 在 AI 分支完成 API 变更并准备合并。

工作流

确认项目/分支
  -> 如需从代码/文档导入，先做 spec 生成和质量门禁
  -> 设计接口和 Schema
  -> 配置环境和变量
  -> 配置 Mock
  -> 创建接口测试用例
  -> 运行测试并查看报告
  -> 导出/发布文档
  -> 合并或创建 MR

Step 1：确认上下文

按当前 CLI help 确认身份、项目、目标分支和是否需要 AI 分支。

• 用户要直接改主分支/迭代分支时，确认 AI 写入权限或走 AI 分支。
• 如果通过 AI 分支改已有资源，先用 branch pick-to 导入源资源。

Step 2：设计 API 资源

按当前 CLI help 使用 endpoint、schema、response-component、security-scheme、folder 等 API 设计资源命令。

最小边界：endpoint 是接口定义，test-case 是接口下测试用例，不要混写；schema、response-component、security-scheme 等可复用资源应先创建，再由 endpoint 引用；环境变量不要写进 common-parameter。

如果任务是从代码库、PRD 或文档生成并导入 API spec，先读取 ../apifox-import-export/SKILL.md，完成生成器搜索、OpenAPI 指标校验、tags 分组和临时项目导入验证，再进入接口设计或测试补充。

• 先建 schema、response-component、security-scheme 等可复用资源，再引用到 endpoint。
• 创建后必须 endpoint get 验证真实保存结构。

Step 3：配置环境

按当前 CLI help 使用 environment、variables、database-connection、vault 等环境和运行上下文命令。

• 没有合适环境时创建或更新环境。
• 敏感变量不要出现在最终回复中。
• 运行测试和 CI 交付命令建议显式带 --environment，避免默认环境变化导致不可复现。

Step 4：补测试用例

读取 ../apifox-test-case/SKILL.md。

• 不要创建空壳 case。
• 创建后 test-case get 验证步骤、断言、提取器被保存。

Step 5：验证和交付

• 测试报告异常先区分本地报告、云端上传和下载概要；必要时转 apifox-cli-checkup。
• 前端展示异常转 apifox-cli-checkup。
• 需要合并时转 apifox-branch。
• 如果新建 API 的测试运行返回 404 或断言失败，先检查 Mock/环境是否配置，不要直接判定 endpoint 或 test-case 创建失败。Mock 未配置导致运行失败是执行环境问题，不等于设计资产未保存。

不可违反规则

1. 不要跳过 project/branch 确认。
2. 不要直接在受保护主分支写入。
3. 不要只创建接口不验证保存结构。
4. 不要只创建空测试用例。
5. 不要把测试失败当作接口创建失败；分别定位 API 定义、环境、测试用例和执行报告。