improve-operation-ids

Improve SDK method naming from auto-generated to intuitive grouped methods.

When to Use

• SDK methods have ugly auto-generated names like GetApiV1Users

• You want grouped methods like sdk.users.list()

• User says: "ugly method names", "improve operation IDs", "better SDK naming"

Inputs

Input Required Description

OpenAPI spec Yes Spec to improve (-s )

Authentication Yes Via speakeasy auth login or SPEAKEASY_API_KEY env var

Outputs

Output Description

Suggestions Better operation names

Overlay file Optional: saves as overlay (-o )

Prerequisites

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

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

See configure-authentication skill for details.

Check Current State

speakeasy suggest operation-ids -s openapi.yaml

SDK Method Naming

Speakeasy generates grouped SDK methods using x-speakeasy-group :

HTTP Method SDK Usage Operation ID

GET (list) sdk.users.list()

users_list

GET (single) sdk.users.get()

users_get

POST sdk.users.create()

users_create

PUT sdk.users.update()

users_update

PATCH sdk.users.patch()

users_patch

DELETE sdk.users.delete()

users_delete

Use x-speakeasy-group: users and x-speakeasy-name-override: list to achieve this grouping.

Apply Suggestions

Generate overlay

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

Add to workflow and regenerate

speakeasy run --output console

Manual Override

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

This produces: sdk.users.listAll()

What NOT to Do

• Do NOT modify operationIds directly in the source spec if externally managed

• Do NOT use generic names like get , post without context

• Do NOT forget to add the overlay to workflow.yaml after generating

Troubleshooting

Error Cause Solution

Names unchanged Missing overlay in workflow Add overlay to workflow.yaml sources

"unauthorized" Missing API key Set SPEAKEASY_API_KEY env var

Duplicate names Similar endpoints Use unique x-speakeasy-name-override values

Related Skills

• get-ai-suggestions

• Auto-generate naming suggestions

• create-openapi-overlay

• Create custom naming overlays

• regenerate-sdk

• Regenerate with improved names