create-openapi-overlay

用途

create-openapi-overlay 用于在不修改源 OpenAPI 规范的情况下，为 SDK 生成过程定制规范内容。当需要调整 SDK 输出但无法编辑源规范时，可以通过创建 Overlay 文件来实现。典型触发场景包括：用户要求“创建 overlay”“定制 SDK”“无法修改规范”等。

主要能力

Overlay 适合以下定制操作：

重命名操作（使用 x-speakeasy-name-override）
添加描述或摘要
对操作进行分组（使用 x-speakeasy-group）
添加重试配置
将端点标记为已废弃
添加 SDK 专用扩展
在不修改源文件的情况下修复规范问题
添加新的端点或 schema
制作可跨规范版本使用的可移植补丁

使用方式

输入

目标规范（必填）：需要定制的规范
定制内容（必填）：要应用的更改，如分组、命名等

输出

Overlay 文件：包含 JSONPath 定位更改的 YAML 文件

手动创建 Overlay

使用以下模板结构创建 Overlay 文件：

overlay: 1.0.0
info:
  title: My Overlay
  version: 1.0.0
actions:
  - target: "$.paths['/example'].get"
    update:
      x-speakeasy-group: example

也可以通过对比两个规范来生成 Overlay：

speakeasy overlay compare -b <before-spec> -a <after-spec> -o <output-overlay>

示例 Overlay

overlay: 1.0.0
info:
  title: SDK Customizations
  version: 1.0.0
actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: list
  - target: "$.paths['/users'].post"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: create
  - target: "$.paths['/users/{id}'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: get
  - target: "$.paths['/users/{id}'].delete"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: delete
      deprecated: true

上述配置会生成：sdk.users.list()、sdk.users.create()、sdk.users.get()、sdk.users.delete()。

JSONPath 定位

$.paths['/users'].get：选择 GET /users 操作
$.paths['/users/{id}'].*：选择 /users/{id} 上的所有操作
$.components.schemas.User：选择 User schema
$.info：选择 API info 对象

适用场景

需要定制 SDK 输出但无法修改源规范
为分组、命名或重试添加 x-speakeasy 扩展
在不编辑原始文件的情况下修复 lint 问题
用户明确表示“创建 overlay”“定制 SDK”“无法修改规范”

限制与注意事项

以下情况不应使用 Overlay：

不要用 Overlay 处理无效的 YAML/JSON 语法错误
不要尝试用 Overlay 去重 schema（需要结构化分析）
不要用 Overlay 修复损坏的 $ref 路径，应直接修复源规范

故障排查

“target not found”：JSONPath 与规范结构不匹配，需通过规范检查验证确切路径
更改未生效：Overlay 未加入工作流，需将 Overlay 添加到 workflow.yaml 的 sources 中
YAML 解析错误：Overlay 语法无效，需检查 YAML 缩进和结构

技能介绍

用途