improve-sdk-naming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

improve-sdk-naming

优化SDK命名

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.

借助AI驱动的建议或手动覆盖来优化SDK方法命名。涵盖自动

speakeasy suggest

命令以及使用

x-speakeasy-group

和

x-speakeasy-name-override

扩展的手动命名两种方式。

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)

当你想要从Speakeasy获取AI驱动的建议时，使用此技能：

SDK方法存在
```
GetApiV1Users
```
这类丑陋的自动生成名称
希望Speakeasy AI提供更优的Operation ID建议
希望获取AI生成的错误类型建议
希望通过
```
speakeasy suggest
```
自动提升规范质量
用户提及："suggest improvements"、"speakeasy suggest"、"AI suggestions"、"suggest operation-ids"、"suggest error-types"、"get AI recommendations"

不适用场景：手动创建覆盖层（请改用

manage-openapi-overlays

技能）

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` )

输入项	是否必填	描述
OpenAPI 规范	是	规范文件路径（ `-s` 参数）
身份验证	是	通过 `speakeasy auth login` 或 `SPEAKEASY_API_KEY` 环境变量进行验证
输出文件	否	覆盖层输出路径（ `-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` )

输出项	描述
建议内容	更优的操作名称或错误类型，将打印至控制台
覆盖层文件	可选：将建议保存为YAML格式的覆盖层文件（通过 `-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

在非交互式环境（CI/CD、AI Agent）中，需将API密钥设置为环境变量：

bash

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

在交互式环境中，可直接进行身份验证：

bash

speakeasy auth login

Command

命令示例

AI-Powered Suggestions

AI驱动的建议

bash

undefined

bash

undefined

Suggest better operation IDs (SDK method names)

建议更优的Operation ID（即SDK方法名称）

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

undefined

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

undefined

Check Current Operation IDs

查看当前Operation ID

Run the suggest command without

-o

to preview what would change:

bash

speakeasy suggest operation-ids -s openapi.yaml

运行不带

-o

参数的suggest命令，可预览将要进行的更改：

bash

speakeasy suggest operation-ids -s openapi.yaml

SDK Method Naming Convention

SDK方法命名规范

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.

Speakeasy会根据Operation ID生成分组的SDK方法。命名规范使用

x-speakeasy-group

指定命名空间，

x-speakeasy-name-override

指定方法名称。

HTTP方法	SDK使用方式	Operation ID
GET（列表）	`sdk.users.list()`	`users_list`
GET（单个资源）	`sdk.users.get()`	`users_get`
POST	`sdk.users.create()`	`users_create`
PUT	`sdk.users.update()`	`users_update`
DELETE	`sdk.users.delete()`	`users_delete`

Operation ID的格式为

{group}_{method}

。Speakeasy会通过下划线拆分，在生成的SDK中创建命名空间和方法名称。

Example

示例流程

Step 1: Get AI Suggestions

步骤1：获取AI建议

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
```

bash

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

该命令会分析你的规范并生成覆盖层，将如下名称进行转换：

```
get_api_v1_users_list
```
->
```
listUsers
```
```
post_api_v1_users_create
```
->
```
createUser
```

Step 2: Review and Apply the Overlay

步骤2：审核并应用覆盖层

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.

AI生成的覆盖层（通过

-o

参数生成）会使用

x-speakeasy-group

和

x-speakeasy-name-override

来实现命名优化。

注意：若需手动创建覆盖层，请使用

manage-openapi-overlays

技能，而非本技能。

Step 3: Add the Overlay to workflow.yaml

步骤3：将覆盖层添加至workflow.yaml

yaml

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

yaml

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

Step 4: Regenerate the SDK

步骤4：重新生成SDK

bash

speakeasy run --output console

bash

speakeasy run --output console

Error Type Suggestions

错误类型建议

The

suggest error-types

command analyzes your API and suggests structured error responses:

bash

speakeasy suggest error-types -s openapi.yaml

This suggests:

Common HTTP error codes (400, 401, 404, 500)
Custom error schemas appropriate for your API

Output as an overlay:

bash

speakeasy suggest error-types -s openapi.yaml -o error-types-overlay.yaml

suggest error-types

命令会分析你的API并建议结构化的错误响应：

bash

speakeasy suggest error-types -s openapi.yaml

该命令会建议：

常见HTTP错误码（400、401、404、500）
适合你的API的自定义错误 Schema

将建议输出为覆盖层：

bash

speakeasy suggest error-types -s openapi.yaml -o error-types-overlay.yaml

What NOT to Do

注意事项

Do NOT modify operationIds directly in the source spec if it is externally managed. Use overlays instead.
Do NOT use generic names like
```
get
```
or
```
post
```
without a group. Always pair
```
x-speakeasy-name-override
```
with
```
x-speakeasy-group
```
.
Do NOT forget to add the generated overlay to
```
workflow.yaml
```
after creating it. Without this step, the names will not change in the generated SDK.
Do NOT create duplicate operation names across different groups. Each
```
{group}_{method}
```
combination must be unique.

请勿直接修改外部管理的源规范中的Operation ID，应使用覆盖层替代。
请勿在未指定分组的情况下使用
```
get
```
或
```
post
```
这类通用名称。务必将
```
x-speakeasy-name-override
```
与
```
x-speakeasy-group
```
配合使用。
请勿在创建覆盖层后忘记将其添加至
```
workflow.yaml
```
。若不执行此步骤，生成的SDK中的名称不会发生变化。
请勿在不同分组中创建重复的方法名称。每个
```
{group}_{method}
```
组合必须唯一。

Troubleshooting

故障排除

Error	Cause	Solution
"unauthorized"	Missing or invalid API key	Set `SPEAKEASY_API_KEY` env var or run `speakeasy auth login`
Names unchanged after regeneration	Overlay not added to workflow	Add the overlay to the `overlays` list in `workflow.yaml`
No suggestions returned	Spec already has good naming	No action needed; names are already well-structured
Duplicate method names	Similar endpoints share names	Use unique `x-speakeasy-name-override` values for each endpoint
Timeout during suggest	Very large spec	Try running on a smaller subset or increase timeout

错误信息	原因	解决方案
"unauthorized"	缺少或无效的API密钥	设置 `SPEAKEASY_API_KEY` 环境变量，或运行 `speakeasy auth login` 进行登录
重新生成后名称未变化	覆盖层未添加至工作流	将覆盖层添加至 `workflow.yaml` 的 `overlays` 列表中
未返回任何建议	规范的命名已较为合理	无需操作；当前名称已符合良好的结构化要求
方法名称重复	相似端点使用了相同的名称	为每个端点使用唯一的 `x-speakeasy-name-override` 值
suggest命令超时	规范文件过大	尝试在较小的子集上运行，或增加超时时间