get-ai-suggestions

用途

get-ai-suggestions 用于为 OpenAPI 规范获取 AI 驱动的改进建议，主要面向希望自动提升规范质量、优化 SDK 方法命名或补充错误类型定义的场景。触发方式包括用户提出“suggest improvements”“improve my spec”“speakeasy suggest”“better operation names”等需求。

主要能力

该技能通过 speakeasy suggest 命令提供两类建议：

Operation ID 建议：将自动生成的方法名转换为更直观的 SDK 方法名，例如 get_api_v1_users_list 转换为 listUsers，post_api_v1_users_create 转换为 createUser。
错误类型建议：分析 API 并建议结构化的错误响应，包括常见 HTTP 错误码（400、401、404、500）以及自定义错误 schema。

使用方式

输入

OpenAPI spec（必填）：待分析的规范，通过 -s 指定。
认证（必填）：通过 speakeasy auth login 或 SPEAKEASY_API_KEY 环境变量提供。

输出

建议内容：打印到控制台，或通过 -o 输出为 overlay 文件。
Overlay 文件（可选）：将建议保存为 overlay。

前置条件

在非交互环境（CI/CD、AI 智能体）中，需设置：

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

常用命令

建议更好的 operation ID（方法名）

speakeasy suggest operation-ids -s <spec-path>

建议错误类型定义

speakeasy suggest error-types -s <spec-path>

将建议输出为 overlay 文件

speakeasy suggest operation-ids -s <spec-path> -o suggested-overlay.yaml

应用建议

生成带建议的 overlay

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

添加到 workflow.yaml

sources: my-api: inputs: - location: ./openapi.yaml overlays: - location: ./operation-ids-overlay.yaml

重新生成

speakeasy run --output console

适用场景

希望获得 AI 生成的 operation ID 或错误类型建议。
希望自动提升规范质量。
需要将建议以 overlay 形式纳入 SDK 生成工作流。

限制与故障排查

若出现“unauthorized”，通常是缺少 API key，需设置 SPEAKEASY_API_KEY 环境变量。
若无建议，可能是规范命名已经良好，无需操作。
若超时，可能是规范过大，可尝试拆分较小部分或延长等待时间。

技能介绍

用途