系列08-Swagger 导入到 AI 生成接口用例：接口自动化从零到 nightly 回归（实操）

联调阶段用 Postman 发几条请求很容易；难的是 100 个接口怎么管、用例怎么批量起、谁来保证每晚还在跑。

本文按一条可落地的工程路径讲：Swagger 资产化 → 调试确认 → AI 起量 → 套件链式变量 → Token 授权 → 计划/cron 回归。以 BrickCore（FastAPI + httpx 自研执行引擎）为例；步骤可映射到其它支持 OpenAPI 导入的平台。

---

演示与源码

	地址
功能演示	http://43.142.83.156/showcase/ （「接口用例 AI 生成」含录屏；平台 admin / BrickCore123456）
开源仓库	https://gitee.com/BanZhuanKeOrz/BrickCore

线上路径：接口自动化 → 接口管理 / 测试计划 / 定时任务。建议先看录屏，再跟下面九节操作。

---

一、目标：从「能发请求」到「可运维回归」

阶段	交付物	常见工具
联调	单接口通	Postman
资产化	接口元数据入库	Swagger 导入
起量	批量用例 + 断言	AI 生成 + 人工审
链路	登录→业务 extractors	测试套件 + 变量池
运维	nightly + 报告	测试计划 + cron

原则：Postman 继续联调；回归资产放平台，避免 collection JSON 散落个人账号。

---

二、准备清单

项	说明
OpenAPI JSON	Swagger UI 导出或 CI 产物 openapi.json
测试环境 Host	如 https://api.test.example.com，只配在 Environment
鉴权	需登录的 API 配 Token 授权（见第七节）
LLM	平台配置 → AI 模型 → 场景 api_case 绑定文本模型

---

三、Step 1～2：项目、环境、Swagger 导入

3.1 项目与环境

1. 项目配置 → 项目列表 新建/选择项目
2. 环境配置：Host = 测试 base_url；可选全局变量 tenant_id、app_id
3. 模块/目录 按业务划分（用户 / 订单 / 支付）

约定：接口 path 保持 /api/v1/... 相对路径；Host 只在环境，切换预发只改 env_id。

3.2 Swagger 批量导入

接口自动化 → 接口管理 → 导入 → Swagger，上传 JSON → 按 path + method 生成 ApiDefinition。

3.3 源码：为什么必须展开 $ref

AI 生成断言依赖 request/response schema。body 若是 $ref 不展开，schema 为空，AI 只能猜字段：

# routers/http/apis.py — import_swagger
def _resolve_ref(ref_path, components):
    if not ref_path.startswith('#/components/schemas/'):
        return {}
    schema_name = ref_path.replace('#/components/schemas/', '')
    return components.get('schemas', {}).get(schema_name, {})

导入后验收：点开一条 POST，确认 body 字段列表非空；若为空，检查 Swagger 是否规范写在 components/schemas。

---

四、Step 3：单接口调试（再 AI）

1. 打开接口 → 选环境 → 发送
2. 看 status / body，微调 headers、query、body
3. 通了的接口再 AI 生成——减少 AI 在 404/401 接口上「一本正经地编断言」

---

五、Step 4：AI 生成接口用例

1. 勾选一个或多个 ApiDefinition
2. AI 生成接口用例（基于 method、path、schema）
3. 典型自动生成：status_code、关键 json_path、常见 extractors（token、id）
4. 必须人工审查（见 5.2）

5.1 源码：入库前校验与 normalize

# routers/ai/generate.py
required_fields = {"name", "request_headers", "request_params", "request_body",
                   "assertions", "extractors"}

def _normalize_extractors(extractors):
    # 兼容 AI 输出 property / json_path → 统一为 source=json + path

缺 assertions 整批拒绝，避免执行器 500；property 误写字段会自动纠正。

Prompt 场景 api_case_generation（core/ai_prompts.py）约束 LLM 按接口 schema 写断言，仍 不能替代 业务必填字段的人工补全。

5.2 审查清单（生成后、入套件前）

检查	不合格
断言覆盖业务字段	只有 code==0
必填 body 字段	AI 漏传导致 422
extractors 路径	$.data.token 与真实 JSON 不符
鉴权 Header	应走 Token 授权而非写死 token
破坏性接口	POST 删库类需改环境或 mock

---

六、Step 5：登录链路 + 变量池

用例 1：登录

{
  "extractors": [{"name": "token", "source": "json", "path": "$.data.token"}],
  "assertions": [{"type": "status_code", "operator": "equals", "expected": 200}]
}

用例 2：业务

{
  "request_headers": [{"key": "Authorization", "value": "Bearer ${{token}}"}],
  "assertions": [{"type": "json_path", "target": "$.data.id", "operator": "exists"}]
}

加入同一 测试套件（顺序执行）。引擎侧（api_suite_runner.py）：

for case_id in case_ids:
    result = await runner(..., accumulated_vars, ...)
    accumulated_vars.update(result.extracted_vars or {})

等价 Postman 的 pm.environment.set，但是 配置化 JSON，可落库、可审计。

单用例执行时变量合并顺序（run_single_case）：项目 global_vars < 环境 global_vars < 套件传入 < Token 授权。

---

七、Step 6：Token 授权（多环境）

每条用例手写 Bearer 不可维护：

1. 接口自动化 → Token 授权
2. 绑定登录接口 + extractors + ttl_minutes / 提前刷新
3. 执行前 inject_auth_variables（Redis 锁防并发重复登录）
4. 切换测试/预发 只换 env_id

---

八、Step 7～8：计划执行与定时回归

8.1 测试计划

1. 测试计划 → 新建，挂载套件
2. 选环境 → 执行
3. 看 计划 / 套件 / 用例 三级报告；失败展开 request_detail、assertions expected/actual

8.2 定时任务

定时任务 绑定计划 + 环境，cron 如 0 2 * * *：

• 调度存 Redis JobStore（APScheduler），与手动执行走同一 exec 服务
• 触发后写 ApiPlanRunRecord，看板可查历史通过率
• 可选 邮件 / 钉钉 / 企微 通知（系统管理 → 通知配置）

---

九、执行链路（源码一图读懂）

Swagger 导入 → ApiDefinition
    → AI 生成 → ApiTestCase（normalize）
    → 套件顺序执行 → run_single_case（httpx）
        → merge 变量 → inject_auth → 替换 ${{var}}
        → 断言 evaluate_assertion → extract → accumulated_vars
    → 计划/cron → ApiPlanRunRecord 报告

排错：单用例 debug 后查 api_case_run_record.request_detail，看 URL 里 ${{var}} 是否已替换。

---

十、常见失败排错

现象	原因	处理
401	Token 未注入/过期	Token 授权、环境变量
${{var}} 原样	extract 失败或套件乱序	看 extractors、套件顺序
404	Host + path 拼错	环境 Host；path 相对路径
断言全过业务错	断言太弱	补 json_path 业务字段
AI 断言离谱	response schema 空	回到 §3.3 查 $ref
cron 没跑	任务未启用/Redis	定时任务列表 status

---

十一、小结

1. Swagger 解决接口 资产录入；$ref 展开决定 AI 质量。
2. AI 起量 + 人工审查；destructive 接口重点看。
3. 套件变量池 + Token 授权 组成可维护链路。
4. 计划 + cron 把回归从「记得点」变成「每晚自动跑」。
5. 联调 Postman，回归放平台。

---

附录 A：源码文件索引

顺序	文件	关注点
1	routers/http/apis.py	import_swagger、_resolve_ref
2	routers/ai/generate.py	API 用例 normalize/校验
3	routers/http/suites.py	run_single_case、httpx
4	core/api_suite_runner.py	accumulated_vars、hooks
5	core/api_auth_service.py	inject_auth_variables
6	routers/http/cron.py	APScheduler + Redis
7	routers/http/plan.py	计划执行与报告

---

支持与交流

• 演示：http://43.142.83.156/showcase/ · 源码：https://gitee.com/BanZhuanKeOrz/BrickCore
• 觉得有用欢迎 Star ⭐，问题评论区留言或 Gitee Issues