SuperAPI AI 工具集

improve-operation-ids

编程与开发

查看项目

更新于 10-16 05:44

技能介绍

用途:改善 SDK 方法命名,把 OpenAPI 自动生成的名称(如 GetApiV1Users)改为直观的分组方法(如 sdk.users.list())。适用于方法名难读、希望统一分组命名的场景。

主要能力:使用 speakeasy suggest operation-ids 查看当前命名并生成改进建议;可通过 -o 输出 overlay 文件;配合 x-speakeasy-group 与 x-speakeasy-name-override 实现分组命名,例如 GET 列表映射为 users_list,单条为 users_get,POST 为 users_create,PUT 为 users_update,PATCH 为 users_patch,DELETE 为 users_delete。

使用方式:先准备 OpenAPI 规格(必填)与认证。非交互环境设置:export SPEAKASY_API_KEY="<your-api-key>"(资料原文为 SPEAKEASY_API_KEY 环境变量或 speakeasy auth login)。查看状态:speakeasy suggest operation-ids -s openapi.yaml。生成 overlay:speakeasy suggest operation-ids -s openapi.yaml -o operation-ids.yaml。随后在 workflow 中加入该 overlay 并运行 speakeasy run --output console 重新生成。也可手动编写 overlay,在目标路径上更新 x-speakeasy-group 与 x-speakeasy-name-override,如设置 listAll 后生成 sdk.users.listAll()。

限制与注意:若源规格由外部管理,不要直接修改 operationIds;避免使用 get、post 等缺少上下文的泛化名称;生成 overlay 后不要忘记加入 workflow.yaml。常见问题:名称未变化通常是 workflow 未引用 overlay;unauthorized 多为缺少 API 密钥;出现重名应对相似端点使用唯一的 x-speakeasy-name-override。相关技能包括 get-ai-suggestions、create-openapi-overlay、regenerate-sdk。具体认证方式与价格信息暂未提供。