improve-operation-ids

用途

improve-operation-ids 用于改善 SDK 方法的命名。当 SDK 方法带有自动生成的丑陋名称（例如 GetApiV1Users）时，该技能可以将其改进为直观的分组方法名（例如 sdk.users.list()）。它会在 OpenAPI 规范基础上给出更好的 operation 名称建议，并可选地保存为 overlay 文件，供后续重新生成 SDK 时使用。

主要能力

检查当前 OpenAPI 规范中的 operation ID 状态。
生成更合理的 operation 名称建议。
可选地将建议保存为 overlay 文件（通过 -o 参数）。
支持通过 x-speakeasy-group 与 x-speakeasy-name-override 实现分组式 SDK 方法命名。

使用方式

检查当前状态：

speakeasy suggest operation-ids -s openapi.yaml

生成 overlay 文件：

speakeasy suggest operation-ids -s openapi.yaml -o operation-ids.yaml

将 overlay 加入工作流并重新生成：

speakeasy run --output console

非交互式环境（CI/CD、AI 代理）需设置认证：

export SPEAKEASY_API_KEY="<your-api-key>"

手动覆盖示例：

overlay: 1.0.0
info:
  title: Custom operation names
  version: 1.0.0
actions:
  - target: "$.paths['/api/v1/users'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: listAll

上述配置会生成：sdk.users.listAll()

输入与输出

输入：

OpenAPI 规范（必需，通过 -s 指定）
认证（必需，通过 speakeasy auth login 或 SPEAKASY_API_KEY 环境变量）

输出：

更好的 operation 名称建议
可选的 overlay 文件（通过 -o 保存）

SDK 方法命名对照

Speakeasy 使用 x-speakeasy-group 生成分组式 SDK 方法：

GET（列表）：sdk.users.list()，operation ID 为 users_list
GET（单个）：sdk.users.get()，operation ID 为 users_get
POST：sdk.users.create()，operation ID 为 users_create
PUT：sdk.users.update()，operation ID 为 users_update
PATCH：sdk.users.patch()，operation ID 为 users_patch
DELETE：sdk.users.delete()，operation ID 为 users_delete

使用 x-speakeasy-group: users 与 x-speakeasy-name-override: list 可实现上述分组。

适用场景

SDK 方法名由自动生成且难以阅读。
希望获得类似 sdk.users.list() 的分组方法。
用户提到“ugly method names”“improve operation IDs”“better SDK naming”等。

限制与注意事项

如果源规范由外部管理，不要直接修改其中的 operationIds。
不要使用缺乏上下文的通用名称（如 get、post）。
生成后不要忘记将 overlay 加入 workflow.yaml。

故障排查

名称未变化：工作流中缺少 overlay，需将 overlay 加入 workflow.yaml 的 sources。
“unauthorized”：缺少 API key，需设置 SPEAKEASY_API_KEY 环境变量。
名称重复：端点相似，需使用唯一的 x-speakeasy-name-override 值。

技能介绍

用途