fix-validation-errors-with-overlays

用途

fix-validation-errors-with-overlays 是一个用于修复 OpenAPI 校验错误的技能，适用于存在 lint 错误但无法修改源规范的场景。它通过生成 overlay（覆盖层）文件来修正问题，而不改动原始规范。

何时使用

存在 lint 错误，但源规范无法编辑
需要添加缺失的描述、标签或操作名称
用户表达类似“fix with overlay”“can't edit spec”“add missing descriptions”的诉求

输入

OpenAPI 规范（必需）：带有校验错误的规范
Lint 输出（可选，有帮助）：需要修复的错误列表

输出

Overlay 文件：针对校验问题的修复内容

适合用 Overlay 修复的问题

操作名称不佳：使用 x-speakeasy-name-override
缺失描述：添加 summary 或 description
缺失标签：添加 tags 数组
需要操作分组：使用 x-speakeasy-group
需要重试配置：使用 x-speakeasy-retries

不应使用 Overlay 修复的问题

无效的 JSON/YAML：源文件存在语法错误，必须修复源文件
缺失必填字段：schema 不完整，必须修复源文件
损坏的 $ref：需要直接修复源文件
错误的数据类型：属于 API 设计问题，需要修改规范

注意：不要尝试用 overlay 修复结构性错误；也不要忽略那些需要修改源规范才能解决的问题。

快速修复流程

# 1. 生成建议
speakeasy suggest operation-ids -s openapi.yaml -o fixes.yaml

# 2. 添加到工作流
# 编辑 .speakeasy/workflow.yaml 以包含 overlay

# 3. 重新生成
speakeasy run --output console

故障排查

Overlay 未生效：原因是没有加入 workflow.yaml，解决方法是把 overlay 添加到 workflow 的 sources.overlays 中
找不到目标：原因是 JSONPath 错误，解决方法是核对路径与规范完全匹配
错误仍然存在：原因是该问题不适合用 overlay 修复，解决方法是检查该问题是否需要修改源规范

技能介绍

用途

何时使用

输入

输出

适合用 Overlay 修复的问题

不应使用 Overlay 修复的问题

快速修复流程

故障排查

相关技能