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
```
自动提升规范质量
用户提及："建议改进"、"speakeasy suggest"、"AI建议"、"建议operation-ids"、"建议错误类型"、"自动优化命名"、"获取AI推荐"

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

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)

Suggest error type definitions

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.

请勿直接修改外部管理的源规范中的operationId，应改用覆盖层。
请勿使用
```
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命令超时	规范文件过大	尝试在较小的子集上运行，或增加超时时间

improve-sdk-naming

Original

Translation

improve-sdk-naming

优化SDK命名

When to Use

适用场景

Inputs

输入参数

Outputs

输出结果

Prerequisites

前置条件

Command

命令示例

AI-Powered Suggestions

AI驱动的建议

Suggest better operation IDs (SDK method names)

推荐更优的operation ID（即SDK方法名称）

Suggest error type definitions

推荐错误类型定义

Output suggestions as an overlay file

将建议输出为覆盖层文件

Check Current Operation IDs

查看当前的operation ID

SDK Method Naming Convention

SDK方法命名规范

Example

示例步骤

Step 1: Get AI Suggestions

步骤1：获取AI建议

Step 2: Review and Apply the Overlay

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

Step 3: Add the Overlay to workflow.yaml

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

Step 4: Regenerate the SDK

步骤4：重新生成SDK

Error Type Suggestions

错误类型建议

What NOT to Do

注意事项

Troubleshooting

故障排除