apifox-workflow-api-lifecycle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API 生命周期工作流

API Lifecycle Workflow

开始前必须读取
../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

闭环，不要仅凭旧文档或记忆写入。

You must read
../apifox-cli/SKILL.md
before starting. If there is a conflict between the old main entry and the domain rules of this workflow, the current CLI help and this workflow shall prevail. Read
apifox-branch
,
apifox-import-export
,
apifox-test-case
step by step; read
apifox-test-scenario
when complex test processes are involved, and read
apifox-test-automation
when execution and CI are involved.

The specific endpoint, schema, environment, test-report commands shall be subject to the current CLI help. This workflow is used for end-to-end delivery from requirements to API assets, testing, reports, and branch merging, focusing on resource order, quality gates, and delivery verification. When the Agent executes, it should prioritize forming a closed-loop of

help/schema -> get -> validate -> write -> run/report

, and should not write based solely on old documents or memory.

适用场景

Applicable Scenarios

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

Create or update a set of interfaces based on requirements.
Organize interfaces, Schema, directories, and tests after importing OpenAPI/Postman.
Generate API spec from code repositories, PRDs, requirement documents, test documents, or discussion content and then import it into Apifox.
Complete Mock, test cases, documents, and publishing settings for interfaces.
Complete API changes in AI branches and prepare for merging.

工作流

Workflow

text

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

text

Confirm project/branch
  -> If importing from code/documents, first perform spec generation and quality gate checks
  -> Design interfaces and Schema
  -> Configure environment and variables
  -> Configure Mock
  -> Create interface test cases
  -> Run tests and view reports
  -> Export/publish documents
  -> Merge or create MR

Step 1：确认上下文

Step 1: Confirm Context

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

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

Confirm identity, project, target branch, and whether an AI branch is required according to the current CLI help.

When the user wants to directly modify the main branch/iteration branch, confirm the AI write permission or use an AI branch.
If modifying existing resources through an AI branch, first import the source resources using
```
branch pick-to
```
.

Step 2：设计 API 资源

Step 2: Design API Resources

按当前 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
```
验证真实保存结构。

Use API design resource commands such as endpoint, schema, response-component, security-scheme, folder according to the current CLI help.

Minimum boundaries: endpoint is the interface definition, test-case is the test case under the interface, do not mix them; reusable resources such as schema, response-component, security-scheme should be created first, then referenced by the endpoint; environment variables should not be written into common-parameter.

If the task is to generate and import API spec from code repositories, PRDs, or documents, first read

../apifox-import-export/SKILL.md

, complete generator search, OpenAPI indicator verification, tags grouping, and temporary project import verification, then proceed to interface design or test supplement.

Create reusable resources such as
```
schema
```
,
```
response-component
```
,
```
security-scheme
```
first, then reference them in the endpoint.
Must use
```
endpoint get
```
to verify the actual saved structure after creation.

Step 3：配置环境

Step 3: Configure Environment

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

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

Use environment and runtime context commands such as environment, variables, database-connection, vault according to the current CLI help.

Create or update the environment if no suitable environment exists.
Sensitive variables should not appear in the final response.
It is recommended to explicitly add
```
--environment
```
when running test and CI delivery commands to avoid irreproducibility caused by changes in the default environment.

Step 4：补测试用例

Step 4: Complete Test Cases

读取

../apifox-test-case/SKILL.md

。

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

Read

../apifox-test-case/SKILL.md

Do not create empty test cases.
Use
```
test-case get
```
to verify that steps, assertions, and extractors are saved after creation.

Step 5：验证和交付

Step 5: Verification and Delivery

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

If there is an exception in the test report, first distinguish between local reports, cloud uploads, and download summaries; transfer to
```
apifox-cli-checkup
```
if necessary.
Transfer to
```
apifox-cli-checkup
```
if there is an exception in front-end display.
Transfer to
```
apifox-branch
```
when merging is required.
If the test run of a newly created API returns 404 or assertion failure, first check whether Mock/environment is configured, and do not directly determine that the endpoint or test-case creation failed. A run failure caused by unconfigured Mock is an execution environment issue, not equivalent to unsaved design assets.

不可违反规则

Non-violable Rules

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

Do not skip project/branch confirmation.
Do not directly write to protected main branches.
Do not create interfaces without verifying the saved structure.
Do not only create empty test cases.
Do not treat test failures as interface creation failures; locate API definition, environment, test cases, and execution reports separately.