用途:create-openapi-overlay 用于在无法修改源 OpenAPI 规范时,通过 overlay 文件定制 SDK 生成结果,如添加 x-speakeasy 扩展实现分组、命名、重试等。
主要能力:支持重命名操作(x-speakeasy-name-override)、添加描述与摘要、分组操作(x-speakeasy-group)、添加重试配置、标记端点弃用、添加 SDK 专用扩展、修复规范问题而不改源文件、新增端点或 schema、制作可跨版本使用的可移植补丁。
使用方式:可手写 overlay 文件,模板含 overlay、info 与 actions,actions 中用 target 指定 JSONPath,update 写入改动;也可用命令 speakeasy overlay compare -b <before-spec> -a <after-spec> -o <output-overlay> 比较两份规范生成 overlay。JSONPath 可定位具体操作、某路径下全部操作、schema 或 info 对象。
示例:对 /users 的 GET、POST 及 /users/{id} 的 GET、DELETE 分别设置 x-speakeasy-group: users 与 x-speakeasy-name-override,分别生成 sdk.users.list()、create()、get()、delete(),DELETE 可标记 deprecated: true。
限制:不要用 overlay 修复 YAML/JSON 语法错误、去重 schema(需结构分析)或修复断裂的 $ref 路径(应改源规范)。若出现 “target not found”,检查 JSONPath 是否匹配;改动未生效时确认 overlay 已加入 workflow.yaml 的 sources;YAML 解析错误需检查缩进与结构。相关技能包括 apply-openapi-overlay、fix-validation-errors-with-overlays、improve-operation-ids、get-ai-suggestions。