diagnose-generation-failure

生成失敗の診断

SDK の生成に失敗した場合は、根本原因を診断し、修正方針を決定します。

使用するタイミング

• speakeasy run がエラーで失敗した
• SDK の生成結果が予想と異なる
• ユーザーが「生成に失敗した」「SDK のビルドエラー」「なぜ生成に失敗したのか」と言っている

入力

入力	必須	説明
OpenAPI 仕様	はい	生成に失敗した仕様のパス
エラー出力	参考	失敗した実行のエラーメッセージ

出力

出力	説明
診断	失敗の根本原因
修正方針	オーバーレイで修正するか、仕様を修正するか、ユーザーの判断を仰ぐか
対応項目	解決するための具体的な手順

診断手順

1. lint を実行して詳細なエラーを確認します：

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

2. 問題を分類します：

   • オーバーレイで修正可能： 説明の欠落、不適切な operation ID
   • 仕様の修正が必要： 無効なスキーマ、必須フィールドの欠落
   • ユーザーの入力が必要： 設計上の判断、認証の設定

判断の指針

問題の種類	修正方針	例
operationId の欠落	オーバーレイ	speakeasy suggest operation-ids を使用
説明の欠落	オーバーレイ	オーバーレイで追加
無効な $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 - オーバーレイで問題を修正する
• setup-sdk-testing - 検証のためのコントラクトテスト
• writing-openapi-specs - 仕様設計のベストプラクティス