Swagger UI只显示Failed to load API definition时，直接请求rest/all/schema通常能看到真正的500异常或报告ID。
curl -sS https://shop.example/rest/all/schema -H 'Authorization: Bearer ***'| 阶段 | 检查内容 |
|---|---|
| 定位 | 常见原因包括webapi.xml指向不存在的方法、接口类型不是有效Service Contract、DocBlock与PHP类型冲突，以及第三方模块生成无法序列化的schema。 |
| 验证 | 修改接口声明后清config缓存，确认schema返回完整JSON，再打开Swagger。不要只修改前端Swagger页面掩盖后端错误。 |
避免误判
测试时固定同一个Store、客户状态和输入数据，并记录修改前后的请求与数据库结果，避免把作用域差异当成随机故障。
