get-ai-suggestions

Use speakeasy suggest for AI-powered spec improvements.

When to Use

• Want AI-generated suggestions for operation IDs or error types

• Looking to improve spec quality automatically

• User says: "suggest improvements", "AI suggestions", "better operation names"

Inputs

Input Required Description

OpenAPI spec Yes Spec to analyze (-s )

Authentication Yes Via speakeasy auth login or SPEAKEASY_API_KEY env var

Outputs

Output Description

Suggestions Printed to console or overlay file (-o )

Overlay file Optional: saves suggestions as overlay

Prerequisites

For non-interactive environments (CI/CD, AI agents), set:

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

See configure-authentication skill for details.

Commands

Suggest better operation IDs (method names)

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

Suggest error type definitions

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

Output suggestions as overlay file

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

Operation ID Suggestions

Transforms auto-generated names into intuitive SDK method names:

• get_api_v1_users_list → listUsers

• post_api_v1_users_create → createUser

Error Type Suggestions

Analyzes your API and suggests structured error responses:

• Common HTTP error codes (400, 401, 404, 500)

• Custom error schemas

Applying Suggestions

Generate overlay with suggestions

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

Add to workflow.yaml

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

Regenerate

speakeasy run --output console

Troubleshooting

Error Cause Solution

"unauthorized" Missing API key Set SPEAKEASY_API_KEY env var

No suggestions Spec already well-named No action needed

Timeout Large spec Try smaller sections or wait longer

Related Skills

• improve-operation-ids

• Detailed guidance on SDK method naming

• create-openapi-overlay

• Create custom overlays beyond suggestions

• fix-validation-errors-with-overlays

• Use suggestions to fix lint errors

• regenerate-sdk

• Apply suggestions and regenerate