Back to Details

manage-openapi-overlays

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

manage-openapi-overlays

管理OpenAPI Overlay

Overlays let you customize an OpenAPI spec for SDK generation without modifying the source. This skill covers creating overlay files, applying them to specs, and using them to fix validation errors.
Overlay允许你在不修改源文件的情况下，针对SDK生成需求定制OpenAPI规范。本技能涵盖创建Overlay文件、将其应用到规范中，以及使用它们修复验证错误。

Content Guides

内容指南

TopicGuide
OpenAPI Validationcontent/validation.md
Security Schemescontent/security-schemes.md
These guides cover validating specs, fixing common issues, and configuring authentication methods.
主题指南
OpenAPI Validationcontent/validation.md
Security Schemescontent/security-schemes.md
这些指南涵盖规范验证、常见问题修复以及认证方法配置。

Authentication

认证

Set 
SPEAKEASY_API_KEY
env var or run 
speakeasy auth login
.
设置
SPEAKEASY_API_KEY
环境变量，或运行
speakeasy auth login
命令。

When to Use

适用场景

Use this skill when you need to manually work with overlay files:
  • Creating an overlay file from scratch with specific JSONPath targets
  • Applying an existing overlay file to a spec
  • Validating overlay syntax and structure
  • Comparing two specs to generate an overlay
  • Understanding overlay mechanics (actions, targets, update/remove)
  • Fixing lint issues via manual overlay creation
  • User says: "create overlay", "apply overlay", "overlay file", "manual overlay", "overlay syntax", "JSONPath targeting", "validate overlay"
NOT for: AI-powered naming suggestions (see 
improve-sdk-naming
instead)
当你需要手动处理Overlay文件时使用本技能：
  • 基于特定JSONPath目标从头创建Overlay文件
  • 将现有Overlay文件应用到规范中
  • 验证Overlay的语法和结构
  • 对比两个规范以生成Overlay
  • 理解Overlay的工作机制（动作、目标、更新/删除）
  • 通过手动创建Overlay修复Lint问题
  • 用户提及以下关键词时触发："create overlay"、"apply overlay"、"overlay file"、"manual overlay"、"overlay syntax"、"JSONPath targeting"、"validate overlay"
不适用场景：AI驱动的命名建议（请使用
improve-sdk-naming
技能）

Inputs

输入项

InputRequiredDescription
Target specYesOpenAPI spec to customize or fix
CustomizationsDependsChanges to apply (groups, names, retries, descriptions)
Overlay fileDependsExisting overlay to apply (for apply workflow)
Lint outputHelpfulValidation errors to fix (for fix workflow)
输入项是否必填描述
Target spec是需要定制或修复的OpenAPI规范
Customizations可选需要应用的修改（分组、命名、重试、描述等）
Overlay file可选待应用的现有Overlay文件（适用于应用流程）
Lint output辅助需要修复的验证错误（适用于修复流程）

Outputs

输出项

OutputDescription
Overlay fileYAML file with JSONPath-targeted changes
Modified specTransformed OpenAPI spec (when applying)
输出项描述
Overlay file包含JSONPath目标修改的YAML文件
Modified spec经过转换的OpenAPI规范（应用Overlay后生成）

Commands

命令

Generate an Overlay by Comparing Specs

通过对比规范生成Overlay

bash
speakeasy overlay compare -b <before-spec> -a <after-spec> -o <output-overlay>
Use this when you have a modified version of a spec and want to capture the differences as a reusable overlay.
bash
speakeasy overlay compare -b <before-spec> -a <after-spec> -o <output-overlay>
当你有一个规范的修改版本，希望将差异捕获为可复用的Overlay时，使用此命令。

Apply an Overlay to a Spec

将Overlay应用到规范

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

Validate an Overlay

验证Overlay

bash
speakeasy overlay validate -o <overlay-path>
bash
speakeasy overlay validate -o <overlay-path>

Creating an Overlay Manually

手动创建Overlay

Create an overlay file with this structure:
yaml
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
Each action has a 
target
(JSONPath expression) and an 
update
(object to merge) or 
remove
(boolean to delete the target).
按照以下结构创建Overlay文件：
yaml
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
（用于删除目标的布尔值）。

Example: SDK Method Naming and Grouping

示例：SDK方法命名与分组

yaml
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
This produces SDK methods: 
sdk.users.list()
, 
sdk.users.create()
, 
sdk.users.get()
, 
sdk.users.delete()
.
yaml
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()
。

Example: Apply Overlay

示例：应用Overlay

bash
undefined
bash
undefined

Apply overlay and write merged spec

应用Overlay并写入合并后的规范

speakeasy overlay apply -s openapi.yaml -o sdk-overlay.yaml --out openapi-modified.yaml
speakeasy overlay apply -s openapi.yaml -o sdk-overlay.yaml --out openapi-modified.yaml

Compare two specs to generate an overlay

对比两个规范以生成Overlay

speakeasy overlay compare -b original.yaml -a modified.yaml -o changes-overlay.yaml
undefined
speakeasy overlay compare -b original.yaml -a modified.yaml -o changes-overlay.yaml
undefined

Using in Workflow (Recommended)

推荐工作流用法

Instead of applying overlays manually, add them to 
.speakeasy/workflow.yaml
:
yaml
sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./naming-overlay.yaml
      - location: ./grouping-overlay.yaml
Overlays are applied in order. Later overlays can override earlier ones. This approach ensures overlays are always applied during 
speakeasy run
.
建议不要手动应用Overlay，而是将它们添加到
.speakeasy/workflow.yaml
中：
yaml
sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./naming-overlay.yaml
      - location: ./grouping-overlay.yaml
Overlay会按顺序应用，后续的Overlay可以覆盖之前的设置。这种方式确保在运行
speakeasy run
时，Overlay始终会被应用。

Common Fix Patterns

常见修复模式

Use overlays to fix validation issues when you cannot edit the source spec.
IssueOverlay Fix
Poor operation namesAdd 
x-speakeasy-name-override
to the operation
Missing descriptionsAdd 
summary
or 
description
to the operation
Missing tagsAdd 
tags
array to the operation
Need operation groupingAdd 
x-speakeasy-group
to operations
Need retry configAdd 
x-speakeasy-retries
to operations or globally
Deprecate an endpointAdd 
deprecated: true
to the operation
Add SDK-specific metadataAdd any 
x-speakeasy-*
extension
当你无法编辑源规范时，可使用Overlay修复验证问题。
问题Overlay修复方案
操作名称不佳为操作添加
x-speakeasy-name-override
缺少描述为操作添加
summary
或
description
缺少标签为操作添加
tags
数组
需要操作分组为操作添加
x-speakeasy-group
需要重试配置为操作或全局添加
x-speakeasy-retries
弃用端点为操作添加
deprecated: true
添加SDK专属元数据添加任意
x-speakeasy-*
扩展

Fix Workflow

修复工作流

bash
undefined
bash
undefined

1. Validate the spec to identify issues

1. 验证规范以识别问题

speakeasy lint openapi --non-interactive -s openapi.yaml
speakeasy lint openapi --non-interactive -s openapi.yaml

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

2. 创建Overlay文件，针对每个问题进行修复（参考上述模式）

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

3. 在workflow.yaml的sources.overlays中添加Overlay

4. Regenerate the SDK

4. 重新生成SDK

speakeasy run --output console
undefined
speakeasy run --output console
undefined

Speakeasy Extensions Reference

Speakeasy扩展参考

Extensions (
x-speakeasy-*
) customize SDK generation. Apply them via overlays.
ExtensionApplies ToPurpose
x-speakeasy-retries
Operation or rootConfigure retry behavior
x-speakeasy-pagination
OperationEnable automatic pagination
x-speakeasy-name-override
OperationOverride SDK method name
x-speakeasy-group
OperationGroup methods under namespace
x-speakeasy-unknown-values
Schema with enumAllow unknown enum values
x-speakeasy-globals
RootDefine SDK-wide parameters
x-speakeasy-custom-security-scheme
Security schemeMulti-part custom auth
扩展（
x-speakeasy-*
）用于定制SDK生成，可通过Overlay应用。
扩展适用对象用途
x-speakeasy-retries
操作或根节点配置重试行为
x-speakeasy-pagination
操作启用自动分页
x-speakeasy-name-override
操作覆盖SDK方法名称
x-speakeasy-group
操作将方法分组到命名空间下
x-speakeasy-unknown-values
带枚举的Schema允许未知枚举值
x-speakeasy-globals
根节点定义SDK级别的参数
x-speakeasy-custom-security-scheme
安全方案多部分自定义认证

Retries

重试

yaml
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
yaml
actions:
  - target: "$.paths['/resources'].get"  # 或使用"$"设置全局
    update:
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 500      # 毫秒
          maxInterval: 60000        # 毫秒
          maxElapsedTime: 3600000   # 毫秒
          exponent: 1.5
        statusCodes: ["5XX", "429"]
        retryConnectionErrors: true

Pagination

分页

Offset/Limit:
yaml
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
Cursor:
yaml
actions:
  - target: "$.paths['/events'].get"
    update:
      x-speakeasy-pagination:
        type: cursor
        inputs:
          - name: cursor
            in: parameters
            type: cursor
        outputs:
          results: $.events
          nextCursor: $.next_cursor
偏移量/限制：
yaml
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
游标：
yaml
actions:
  - target: "$.paths['/events'].get"
    update:
      x-speakeasy-pagination:
        type: cursor
        inputs:
          - name: cursor
            in: parameters
            type: cursor
        outputs:
          results: $.events
          nextCursor: $.next_cursor

Open Enums (Anti-Fragility)

开放枚举（抗脆弱性）

Prevent SDK breakage when APIs return new enum values:
yaml
actions:
  - target: "$.components.schemas.Status"
    update:
      x-speakeasy-unknown-values: allow
For all enums (add 
x-speakeasy-jsonpath: rfc9535
at overlay root):
yaml
actions:
  - target: $..[?length(@.enum) > 1]
    update:
      x-speakeasy-unknown-values: allow
防止API返回新枚举值时导致SDK崩溃：
yaml
actions:
  - target: "$.components.schemas.Status"
    update:
      x-speakeasy-unknown-values: allow
针对所有枚举（在Overlay根节点添加
x-speakeasy-jsonpath: rfc9535
）：
yaml
actions:
  - target: $..[?length(@.enum) > 1]
    update:
      x-speakeasy-unknown-values: allow

Global Headers

全局请求头

Add SDK-wide headers as constructor options:
yaml
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
Result: 
client = SDK(api_key="...", tenant_id="tenant-123")
添加SDK级别的请求头作为构造函数选项：
yaml
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")

Custom Security Schemes

自定义安全方案

For complex auth (HMAC, multi-part credentials):
yaml
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: []
With 
envVarPrefix: MYAPI
in gen.yaml, generates env var support for 
MYAPI_KEY_ID
, 
MYAPI_KEY_SECRET
.
针对复杂认证（HMAC、多部分凭证）：
yaml
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 Targeting Reference

JSONPath定位参考

TargetSelects
$.paths['/users'].get
GET /users operation
$.paths['/users/{id}'].*
All operations on /users/{id}
$.paths['/users'].get.parameters[0]
First parameter of GET /users
$.components.schemas.User
User schema definition
$.components.schemas.User.properties.name
Name property of User schema
$.info
API info object
$.info.title
API title
$.servers[0]
First server entry
目标路径选中对象
$.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]
第一个服务器条目

What NOT to Do

注意事项

  • Do NOT use overlays for invalid YAML/JSON syntax errors -- fix the source file
  • Do NOT try to fix broken 
    $ref
    paths with overlays -- fix the source spec
  • Do NOT use overlays to fix wrong data types -- this is an API design issue
  • Do NOT try to deduplicate schemas with overlays -- requires structural analysis
  • Do NOT ignore errors that require source spec fixes -- overlays cannot solve everything
  • Do NOT modify source OpenAPI specs directly if they are externally managed
  • Do NOT use a 
    speakeasy overlay create
    command -- it does not exist
  • 请勿使用Overlay修复无效的YAML/JSON语法错误——请直接修复源文件
  • 请勿尝试使用Overlay修复损坏的
    $ref
    路径——请直接修复源规范
  • 请勿使用Overlay修复错误的数据类型——这属于API设计问题
  • 请勿尝试使用Overlay去重Schema——这需要结构分析
  • 请勿忽略需要修复源规范的错误——Overlay无法解决所有问题
  • 请勿直接修改外部管理的OpenAPI源规范
  • 请勿使用
    speakeasy overlay create
    命令——该命令不存在

Troubleshooting

故障排除

ErrorCauseSolution
"target not found"JSONPath does not match spec structureVerify exact path and casing by inspecting the spec
Changes not appliedOverlay not in workflowAdd overlay to 
sources.overlays
in 
workflow.yaml
"invalid overlay"Malformed YAMLCheck overlay structure: needs 
overlay
, 
info
, 
actions
YAML parse errorInvalid overlay syntaxCheck YAML indentation and quoting
No changes visibleWrong target pathUse 
$.paths['/exact-path']
with exact casing
Errors persist after overlayIssue not overlay-appropriateCheck if the issue requires a source spec fix instead
Overlay order conflictLater overlay overrides earlierReorder overlays in 
workflow.yaml
or merge into one file
错误原因解决方案
"target not found"JSONPath与规范结构不匹配检查规范结构，确认路径和大小写完全一致
修改未生效Overlay未加入工作流在
workflow.yaml
的
sources.overlays
中添加Overlay
"invalid overlay"YAML格式错误检查Overlay结构：必须包含
overlay
、
info
、
actions
YAML解析错误Overlay语法无效检查YAML缩进和引号使用
无可见修改目标路径错误使用
$.paths['/exact-path']
确保路径和大小写完全匹配
应用Overlay后错误仍存在问题不适用于Overlay修复检查该问题是否需要直接修复源规范
Overlay顺序冲突后续Overlay覆盖了之前的设置在
workflow.yaml
中调整Overlay顺序，或合并为单个文件