manage-openapi-overlays

manage-openapi-overlays

Overlay 可让你在不修改源文件的情况下自定义 OpenAPI 规范，以用于 SDK 生成。本技能介绍如何创建 overlay 文件、将其应用于规范，以及使用它们修复验证错误。

内容指南

主题	指南
OpenAPI 验证	content/validation.md
安全方案	content/security-schemes.md

这些指南介绍如何验证规范、修复常见问题，以及配置身份验证方法。

身份验证

设置 SPEAKEASY_API_KEY 环境变量，或运行 speakeasy auth login。

适用场景

当你需要手动处理 overlay 文件时，请使用此技能：

• 使用特定的 JSONPath 目标从头创建 overlay 文件
• 将现有 overlay 文件应用于规范
• 验证 overlay 语法和结构
• 比较两个规范以生成 overlay
• 理解 overlay 的工作机制（操作、目标、更新/移除）
• 通过手动创建 overlay 修复 lint 问题
• 用户提到：“创建 overlay”、“应用 overlay”、“overlay 文件”、“手动 overlay”、“overlay 语法”、“JSONPath 定位”、“验证 overlay”

不适用于：AI 驱动的命名建议（请改用 improve-sdk-naming）

输入

输入	必需	说明
目标规范	是	要自定义或修复的 OpenAPI 规范
自定义内容	视情况而定	要应用的更改（分组、名称、重试、描述）
Overlay 文件	视情况而定	要应用的现有 overlay（用于应用工作流）
Lint 输出	有帮助	要修复的验证错误（用于修复工作流）

输出

输出	说明
Overlay 文件	使用 JSONPath 指定目标的 YAML 文件，其中包含要应用的更改
修改后的规范	转换后的 OpenAPI 规范（应用 overlay 时）

命令

通过比较规范生成 Overlay

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

如果你有一份修改后的规范，并希望将差异保存为可重复使用的 overlay，请使用此命令。

将 Overlay 应用于规范

speakeasy overlay apply -s <spec-path> -o <overlay-path> --out <output-path>

验证 Overlay

speakeasy overlay validate -o <overlay-path>

手动创建 Overlay

按以下结构创建 overlay 文件：

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

每个操作都有一个 target（JSONPath 表达式），以及一个 update（要合并的对象）或 remove（用于删除目标的布尔值）。

示例：SDK 方法命名和分组

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 方法：sdk.users.list()、sdk.users.create()、sdk.users.get()、sdk.users.delete()。

示例：应用 Overlay

# Apply overlay and write merged spec
speakeasy overlay apply -s openapi.yaml -o sdk-overlay.yaml --out openapi-modified.yaml

# Compare two specs to generate an overlay
speakeasy overlay compare -b original.yaml -a modified.yaml -o changes-overlay.yaml

在工作流中使用（推荐）

与其手动应用 overlay，不如将它们添加到 .speakeasy/workflow.yaml：

sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./naming-overlay.yaml
      - location: ./grouping-overlay.yaml

Overlay 会按顺序应用。后续的 overlay 可以覆盖之前的 overlay。这样可确保每次运行 speakeasy run 时都会应用这些 overlay。

常见修复模式

当你无法编辑源规范时，可以使用 overlay 修复验证问题。

问题	Overlay 修复
操作名称不理想	为操作添加 x-speakeasy-name-override
缺少描述	为操作添加 summary 或 description
缺少标签	为操作添加 tags 数组
需要对操作进行分组	为操作添加 x-speakeasy-group
需要配置重试	为操作或全局配置添加 x-speakeasy-retries
弃用端点	为操作添加 deprecated: true
添加 SDK 专属元数据	添加任意 x-speakeasy-* 扩展

修复工作流

# 1. Validate the spec to identify issues
speakeasy lint openapi --non-interactive -s openapi.yaml

# 2. Create an overlay file targeting each issue (see patterns above)

# 3. Add overlay to workflow.yaml under sources.overlays

# 4. Regenerate the SDK
speakeasy run --output console

Speakeasy 扩展参考

扩展（x-speakeasy-*）用于自定义 SDK 生成。通过 overlays 应用扩展。

扩展	应用对象	用途
x-speakeasy-retries	操作或根节点	配置重试行为
x-speakeasy-pagination	操作	启用自动分页
x-speakeasy-name-override	操作	覆盖 SDK 方法名称
x-speakeasy-group	操作	将方法归入命名空间
x-speakeasy-unknown-values	带有 enum 的 Schema	允许未知的 enum 值
x-speakeasy-globals	根节点	定义 SDK 级参数
x-speakeasy-custom-security-scheme	安全方案	多部分自定义身份验证

重试

actions:
  - target: "$.paths['/resources'].get"  # Or "$" for global
    update:
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 500      # ms
          maxInterval: 60000        # ms
          maxElapsedTime: 3600000   # ms
          exponent: 1.5
        statusCodes: ["5XX", "429"]
        retryConnectionErrors: true

分页

偏移量/限制：

actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-pagination:
        type: offsetLimit
        inputs:
          - name: offset
            in: parameters
            type: offset
          - name: limit
            in: parameters
            type: limit
        outputs:
          results: $.data
          numPages: $.meta.total_pages

游标：

actions:
  - target: "$.paths['/events'].get"
    update:
      x-speakeasy-pagination:
        type: cursor
        inputs:
          - name: cursor
            in: parameters
            type: cursor
        outputs:
          results: $.events
          nextCursor: $.next_cursor

开放式枚举（增强健壮性）

当 API 返回新的 enum 值时，防止 SDK 出现故障：

actions:
  - target: "$.components.schemas.Status"
    update:
      x-speakeasy-unknown-values: allow

适用于所有 enum（在 overlay 根节点添加 x-speakeasy-jsonpath: rfc9535）：

actions:
  - target: $..[?length(@.enum) > 1]
    update:
      x-speakeasy-unknown-values: allow

全局请求头

将 SDK 级请求头添加为构造函数选项：

actions:
  - target: $
    update:
      x-speakeasy-globals:
        parameters:
          - $ref: "#/components/parameters/TenantId"
  - target: $.components
    update:
      parameters:
        TenantId:
          name: X-Tenant-Id
          in: header
          schema:
            type: string

结果：client = SDK(api_key="...", tenant_id="tenant-123")

自定义安全方案

适用于复杂身份验证（HMAC、多部分凭据）：

actions:
  - target: $.components
    update:
      securitySchemes:
        hmacAuth:
          type: http
          scheme: custom
          x-speakeasy-custom-security-scheme:
            schema:
              type: object
              properties:
                keyId:
                  type: string
                keySecret:
                  type: string
  - target: $
    update:
      security:
        - hmacAuth: []

在 gen.yaml 中设置 envVarPrefix: MYAPI 后，将生成对 MYAPI_KEY_ID、MYAPI_KEY_SECRET 环境变量的支持。

JSONPath 定位参考

目标	选取内容
$.paths['/users'].get	GET /users 操作
$.paths['/users/{id}'].*	/users/{id} 上的所有操作
$.paths['/users'].get.parameters[0]	GET /users 的第一个参数
$.components.schemas.User	User Schema 定义
$.components.schemas.User.properties.name	User Schema 的 name 属性
$.info	API 信息对象
$.info.title	API 标题
$.servers[0]	第一个服务条目

请勿执行的操作

• 请勿使用 overlays 修复无效的 YAML/JSON 语法错误——应修复源文件
• 请勿尝试通过 overlays 修复损坏的 $ref 路径——应修复源规范
• 请勿使用 overlays 修复错误的数据类型——这是 API 设计问题
• 请勿尝试使用 overlays 对 Schema 去重——这需要结构分析
• 请勿忽略需要修复源规范的错误——overlays 无法解决所有问题
• 请勿直接修改由外部管理的源 OpenAPI 规范
• 请勿使用 speakeasy overlay create 命令——该命令不存在

故障排除

错误	原因	解决方案
"target not found"	JSONPath 与规范结构不匹配	检查规范以确认路径和大小写是否完全正确
更改未应用	Overlay 不在工作流中	将 overlay 添加到 workflow.yaml 的 sources.overlays
"invalid overlay"	YAML 格式错误	检查 overlay 结构：需要 overlay、info、actions
YAML 解析错误	Overlay 语法无效	检查 YAML 缩进和引号
看不到任何更改	目标路径错误	使用大小写完全匹配的 $.paths['/exact-path']
应用 overlay 后错误仍然存在	问题不适合通过 overlay 解决	检查问题是否需要修复源规范
Overlay 顺序冲突	后续 overlay 覆盖了之前的 overlay	在 workflow.yaml 中调整 overlay 顺序，或合并到一个文件中

完成更改后

创建或修改 overlay 文件并将其添加到 workflow.yaml 后，提示用户重新生成 SDK：

Overlay 配置已完成。 是否要立即使用 speakeasy run 重新生成 SDK？

如果用户确认，请运行：

speakeasy run --output console

只有重新生成后，overlay 更改才会在 SDK 中生效。