improve-sdk-naming

Files (1)

• SKILL.md

SKILL.md (first lines)

# improve-sdk-naming

Improve SDK method naming using AI-powered suggestions or manual overrides. Covers both automatic `speakeasy suggest` commands and manual naming with `x-speakeasy-group` and `x-speakeasy-name-override` extensions.

## When to Use

Use this skill when you want **AI-powered suggestions** from Speakeasy:

- SDK methods have ugly auto-generated names like `GetApiV1Users`
- You want Speakeasy AI to suggest better operation IDs
- You want AI-generated suggestions for error types
- Looking to improve spec quality automatically using `speakeasy suggest`
- User says: "suggest improvements", "speakeasy suggest", "AI suggestions", "suggest operation-ids", "suggest error-types", "get AI recommendations"

**NOT for**: Manually creating overlays (see `manage-openapi-overlays` instead)

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| OpenAPI spec | Yes | Path to the spec file (`-s`) |
| Authentication | Yes | Via `speakeasy auth login` or `SPEAKEASY_API_KEY` env var |
| Output file | No | Path for overlay output (`-o`) |

## Outputs

| Output | Description |
|--------|-------------|
| Suggestions | Better operation names or error types printed to console |
| Overlay file | Optional: saves suggestions as an overlay YAML file (`-o`) |

## Prerequisites

For non-interactive environments (CI/CD, AI agents), set the API key as an environment variable:

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

For interactive use, authenticate directly:

```bash
speakeasy auth login
```

## Command

### AI-Powered Suggestions

```bash
# Suggest better operation IDs (SDK method names)
speakeasy suggest operation-ids -s <spec-path>

# Suggest error type definitions
speakeasy suggest error-types -s <spec-path>

# Output suggestions as an overlay file
speakeasy suggest operation-ids -s <spec-path> -o suggested-overlay.yaml
```

### Check Current Operation IDs

Run the suggest command without `-o` to preview what would change:

```bash
speakeasy suggest operation-ids -s openapi.yaml
```

## SDK Method Naming Convention

Speakeasy generates grouped SDK methods from operation IDs. The naming convention uses `x-speakeasy-group` for the namespace and `x-speakeasy-name-override` for the method name.

| 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` |
| DELETE | `sdk.users.delete()` | `users_delete` |

The operation ID format is `{group}_{method}`. Speakeasy splits on the underscore to create the namespace and method name in the generated SDK.

## Example

### Step 1: Get AI Suggestions

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

This analyzes your spec and generates an overlay that transforms names like:
- `get_api_v1_users_list` -> `listUsers`
- `post_api_v1_users_create` -> `createUser`

### Step 2: Review and Apply the Overlay

The AI-generated overlay (from `-o`) creates naming improvements using `x-speakeasy-group` and `x-speakeasy-name-override`.

**Note**: For manual overlay creation, use the `manage-openapi-overlays` skill instead of this skill.

### Step 3: Add the Overlay to workflow.yaml

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

### Step 4: Regenerate the SDK

```bash
speakeasy run --output console
```

## Error Type Suggestions

From speakeasy-api/sdk-generation-skills, Apache-2.0.

More from speakeasy-api/sdk-generation-skills