diagnose-generation-failure

diagnose-generation-failure

当 SDK 生成失败时，诊断根本原因并确定修复策略。

适用场景

• speakeasy run 因错误而失败
• SDK 生成结果出乎意料
• 用户表示：“生成失败”“SDK 构建错误”“为什么生成失败”

输入

输入	必填	描述
OpenAPI 规范	是	生成失败的规范路径
错误输出	有帮助	失败运行中的错误消息

输出

输出	描述
诊断结果	失败的根本原因
修复策略	使用 Overlay、修复规范或由用户决定
操作项	解决问题的具体步骤

诊断步骤

1. 运行 lint 以获取详细错误：

   speakeasy lint openapi --non-interactive -s <spec-path>
   

2. 对问题进行分类：

   • 可通过 Overlay 修复： 缺少描述、操作 ID 不佳
   • 需要修复规范： 架构无效、缺少必填字段
   • 需要用户输入： 设计决策、身份验证设置

决策框架

问题类型	修复策略	示例
缺少 operationId	Overlay	使用 speakeasy suggest operation-ids
缺少描述	Overlay	通过 Overlay 添加
无效的 $ref	询问用户	引用失效，需要修复规范
循环引用	询问用户	需要做出设计决策
缺少安全设置	询问用户	需要确定身份验证设计

不要做的事

• 不要禁用 lint 规则来隐藏错误
• 不要试图逐一修复所有问题
• 不要未经询问就修改源规范
• 不要假设自己可以修复结构性问题

故障排查树

PROBLEM
  │
  ├─ ResponseValidationError at runtime?
  │    └─ SDK types don't match server responses
  │         ├─ Run contract tests to identify mismatches
  │         └─ Fix spec or create overlay to correct types
  │
  ├─ SDK doesn't match live API behavior?
  │    ├─ Spec may have drifted from API
  │    │    → Run contract tests to detect drift
  │    └─ Third-party spec may be inaccurate
  │         → Validate with contract testing before trusting
  │
  ├─ Type mismatch errors in generated SDK?
  │    ├─ At compile time → Check spec schema definitions
  │    └─ At runtime → Server returns unexpected types
  │                    → Contract testing required
  │
  └─ Enum value not recognized?
       └─ API returned value not in spec enum
            ├─ Add missing value to spec/overlay
            └─ Or use open enums for anti-fragility

处理大型 OpenAPI 规范

使用 yq（YAML）或 jq（JSON）检查规范，无需加载完整内容：

# List all paths
yq '.paths | keys' spec.yaml

# Inspect a specific endpoint
yq '.paths["/users/{id}"]' spec.yaml

# List all schema names
yq '.components.schemas | keys' spec.yaml

# List all operationIds
yq '[.paths[][].operationId // empty] | unique' spec.yaml

策略文档

对于复杂问题，请生成一份文档：

## OpenAPI Spec Analysis

### Blocking Issues (require user input)
- [List issues that need human decision]

### Fixable Issues (can use overlays)
- [List issues with proposed overlay fixes]

### Recommended Approach
[Your recommendation]

相关技能

• manage-openapi-overlays - 使用 Overlay 修复问题
• setup-sdk-testing - 用于验证的契约测试
• writing-openapi-specs - 规范设计最佳实践