apply-openapi-overlay

用途

apply-openapi-overlay 用于将一个 overlay 文件应用到 OpenAPI 规范（spec）上，从而对 spec 进行转换。它适合以下情况：

已经准备好一个 overlay 文件，需要将其应用到 spec。
在把 overlay 变更加入工作流之前进行测试。
用户提出“apply overlay”“merge overlay”“overlay apply”等请求。

主要能力

该技能接收源 OpenAPI spec 和 overlay 文件，输出经过转换的 OpenAPI spec。

输入：

OpenAPI spec（必填）：源 spec，通过 -s 指定。
Overlay 文件（必填）：要应用的 overlay，通过 -o 指定。

输出：

修改后的 spec：转换后的 OpenAPI spec，通过 --out 指定。

使用方式

核心命令：

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

示例：

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

在工作流中使用（推荐）

更推荐的做法是把 overlay 加入 workflow.yaml：

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

Overlay 按顺序应用，因此后面的 overlay 可以覆盖前面的 overlay。

适用场景

需要将 overlay 文件应用到 OpenAPI spec 以完成转换。
在正式加入工作流前，先测试 overlay 变更的效果。
通过 workflow.yaml 配置多个 overlay，按顺序叠加应用。

限制与排查

常见错误及处理方式：

“target not found”：JSONPath 未匹配。解决方法是核对路径在 spec 中是否存在，并注意大小写完全一致。
“invalid overlay”：YAML 格式错误。解决方法是检查 overlay 结构是否与 spec 匹配。
未应用任何变更：目标路径错误。解决方法是使用 $.paths['/exact-path'] 语法。

技能介绍

用途