SuperAPI AI 工具集

get-ai-suggestions

通用与其它

查看项目

更新于 10-16 05:44

技能介绍

用途:该技能用于对 OpenAPI 规范做 AI 驱动的改进,主要针对 operation ID 命名和错误类型定义。当用户提到“suggest improvements”“improve my spec”“better operation names”等场景时触发。

主要能力:1)operation ID 建议,把自动生成的名字改成直观的 SDK 方法名,例如 get_api_v1_users_list 转为 listUsers,post_api_v1_users_create 转为 createUser;2)错误类型建议,分析 API 并给出结构化错误响应,覆盖常见 HTTP 错误码(400、401、404、500)和自定义错误 schema。

使用方式:需先配置认证,非交互环境(CI/CD、AI 代理)可执行 export SPEAKY_API_KEY="<your-api-key>",也可通过 speakeasy auth login。基本命令为 speakeasy suggest operation-ids -s <spec-path> 和 speakeasy suggest error-types -s <spec-path>;加 -o 可输出为 overlay 文件,例如 speakeasy suggest operation-ids -s <spec-path> -o suggested-overlay.yaml。生成的 overlay 可加入 workflow.yaml 的 overlays 段,再用 speakeasy run --output console 重新生成。

适用场景:希望自动提升规范质量、改进 SDK 方法命名、补充结构化错误响应,或结合 overlay 修复 lint 问题时。

限制:需要 OpenAPI 规范和有效认证;大规范可能出现超时,可拆分或等待更久;若规范命名已良好则可能没有建议。错误“unauthorized”多为缺少 API key。相关技能包括 improve-operation-ids、create-openapi-overlay、fix-validation-errors-with-overlays、regenerate-sdk。