diagnose-generation-failure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

diagnose-generation-failure

SDK生成失败诊断

When SDK generation fails, diagnose the root cause and determine the fix strategy.

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

When to Use

使用场景

```
speakeasy run
```
failed with errors
SDK generation produced unexpected results
User says: "generation failed", "SDK build error", "why did generation fail"

```
speakeasy run
```
执行出错
SDK生成结果不符合预期
用户反馈：「生成失败」、「SDK构建错误」、「为什么生成失败」

Inputs

输入参数

Input	Required	Description
OpenAPI spec	Yes	Path to spec that failed generation
Error output	Helpful	Error messages from failed run

输入项	是否必填	描述
OpenAPI spec	是	生成失败的spec文件路径
Error output	有帮助	失败执行的错误信息

Outputs

输出结果

Output	Description
Diagnosis	Root cause of failure
Fix strategy	Overlay vs spec fix vs user decision
Action items	Specific steps to resolve

输出项	描述
Diagnosis	失败的根本原因
Fix strategy	修复策略（Overlay修复/规范修复/用户决策）
Action items	具体解决步骤

Diagnosis Steps

诊断步骤

Run lint to get detailed errors:

bash

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

Categorize issues:
- Fixable with overlays: Missing descriptions, poor operation IDs
- Requires spec fix: Invalid schema, missing required fields
- Requires user input: Design decisions, authentication setup

运行lint获取详细错误信息：

bash

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

问题分类：
- 可通过Overlay修复： 缺少描述、操作ID不规范
- 需要修复规范： 无效的schema、缺少必填字段
- 需要用户输入： 设计决策、认证配置

Decision Framework

决策框架

Issue Type	Fix Strategy	Example
Missing operationId	Overlay	Use `speakeasy suggest operation-ids`
Missing description	Overlay	Add via overlay
Invalid $ref	Ask user	Broken reference needs spec fix
Circular reference	Ask user	Design decision needed
Missing security	Ask user	Auth design needed

问题类型	修复策略	示例
缺少operationId	Overlay修复	使用 `speakeasy suggest operation-ids`
缺少描述	Overlay修复	通过Overlay添加
无效的$ref	询问用户	损坏的引用需要修复规范
循环引用	询问用户	需要设计决策
缺少安全配置	询问用户	需要认证设计

What NOT to Do

禁止操作

Do NOT disable lint rules to hide errors
Do NOT try to fix every issue one-by-one
Do NOT modify source spec without asking
Do NOT assume you can fix structural problems

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

Troubleshooting Tree

故障排查树

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

问题
  │
  ├─ 运行时出现ResponseValidationError？
  │    └─ SDK类型与服务器响应不匹配
  │         ├─ 运行契约测试以识别不匹配项
  │         └─ 修复规范或创建Overlay来修正类型
  │
  ├─ SDK与实际API行为不符？
  │    ├─ 规范可能与API出现偏差
  │    │    → 运行契约测试检测偏差
  │    └─ 第三方规范可能不准确
  │         → 在信任前先通过契约测试验证
  │
  ├─ 生成的SDK中出现类型不匹配错误？
  │    ├─ 编译时错误 → 检查规范中的schema定义
  │    └─ 运行时错误 → 服务器返回非预期类型
  │                    → 需要进行契约测试
  │
  └─ 枚举值不被识别？
       └─ API返回了规范枚举中没有的值
            ├─ 将缺失的值添加到规范/Overlay中
            └─ 或者使用开放枚举提高健壮性

Working with Large OpenAPI Specs

处理大型OpenAPI规范

Use

yq

(YAML) or

jq

(JSON) to inspect specs without loading full content:

bash

undefined

使用

yq

（YAML）或

jq

（JSON）工具在不加载完整内容的情况下检查规范：

bash

undefined

List all paths

列出所有路径

yq '.paths | keys' spec.yaml

Inspect a specific endpoint

检查特定端点

yq '.paths["/users/{id}"]' spec.yaml

List all schema names

列出所有schema名称

yq '.components.schemas | keys' spec.yaml

List all operationIds

列出所有operationId

yq '[.paths[][].operationId // empty] | unique' spec.yaml

undefined

yq '[.paths[][].operationId // empty] | unique' spec.yaml

undefined

Strategy Document

策略文档

For complex issues, produce a document:

markdown

undefined

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

markdown

undefined

diagnose-generation-failure

Original

Translation

diagnose-generation-failure

SDK生成失败诊断

When to Use

使用场景

Inputs

输入参数

Outputs

输出结果

Diagnosis Steps

诊断步骤

Decision Framework

决策框架

What NOT to Do

禁止操作

Troubleshooting Tree

故障排查树

Working with Large OpenAPI Specs

处理大型OpenAPI规范

List all paths

列出所有路径

Inspect a specific endpoint

检查特定端点

List all schema names

列出所有schema名称

List all operationIds

列出所有operationId

Strategy Document

策略文档

OpenAPI Spec Analysis

OpenAPI规范分析

Blocking Issues (require user input)

阻塞问题（需要用户输入）

Fixable Issues (can use overlays)

可修复问题（可使用Overlay）

Recommended Approach

推荐方案

Related Skills

相关技能