mcpField
I
improve-sdk-naming

improve-sdk-naming

github.com/speakeasy-api開発1894 回インストール37 週間前に更新
リポジトリ

improve-sdk-naming について

Speakeasy 生成 SDK のメソッド名やエラー型名を改善するスキルです。OpenAPI 仕様を扱う開発者向けに、Speakeasy CLI による AI 提案と、確認後の提案をオーバーレイとして適用する方法を提供します。

主な機能

  1. 01CLI で operation ID を提案
  2. 02構造化エラー型を提案
  3. 03提案をオーバーレイファイルに出力
  4. 04グループ化と名前上書き拡張の利用

活用シーン

  1. 01分かりにくい SDK 自動生成メソッド名の改善
  2. 02再生成前にメソッド名の提案を確認
  3. 03API 仕様への構造化エラー型の提案追加

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/speakeasy-api/sdk-generation-skills --skill improve-sdk-naming

インストール後、Claude Code で/improve-sdk-namingを入力して読み込まれたか確認します。

詳細

improve-sdk-naming

AI を活用した提案または手動でのオーバーライドにより、SDK メソッドの命名を改善します。自動実行する speakeasy suggest コマンドと、x-speakeasy-group および x-speakeasy-name-override 拡張機能を使用した手動の命名の両方を扱います。

使用するタイミング

Speakeasy から AI を活用した提案を得たい場合に、このスキルを使用します。

  • SDK メソッドが GetApiV1Users のような不自然な自動生成名になっている
  • Speakeasy AI に、より適切なオペレーション ID を提案してほしい
  • エラー型の AI 生成による提案がほしい
  • speakeasy suggest を使って、仕様の品質を自動的に改善したい
  • ユーザーが「改善を提案して」「speakeasy suggest」「AI の提案」「オペレーション ID を提案して」「エラー型を提案して」「AI の推奨事項を取得して」と言う場合

対象外：オーバーレイの手動作成（代わりに manage-openapi-overlays を参照してください）

入力

入力必須説明
OpenAPI 仕様はい仕様ファイルのパス（-s）
認証はいspeakeasy auth login または SPEAKEASY_API_KEY 環境変数を使用
出力ファイルいいえオーバーレイ出力先のパス（-o）

出力

出力説明
提案より適切なオペレーション名またはエラー型をコンソールに出力
オーバーレイファイル任意：提案をオーバーレイ YAML ファイルとして保存（-o）

前提条件

非対話型の環境（CI/CD、AI エージェント）では、API キーを環境変数として設定します。

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

対話型の使用では、直接認証します。

speakeasy auth login

コマンド

AI を活用した提案
# 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
現在のオペレーション ID を確認する

変更内容をプレビューするには、-o を付けずに suggest コマンドを実行します。

speakeasy suggest operation-ids -s openapi.yaml

SDK メソッドの命名規則

Speakeasy は、オペレーション ID からグループ化された SDK メソッドを生成します。命名規則では、名前空間に x-speakeasy-group を、メソッド名に x-speakeasy-name-override を使用します。

HTTP メソッドSDK の使用方法オペレーション ID
GET（一覧）sdk.users.list()users_list
GET（単一）sdk.users.get()users_get
POSTsdk.users.create()users_create
PUTsdk.users.update()users_update
DELETEsdk.users.delete()users_delete

オペレーション ID の形式は {group}_{method} です。Speakeasy はアンダースコアで分割し、生成される SDK の名前空間とメソッド名を作成します。

例

ステップ 1：AI の提案を取得する
speakeasy suggest operation-ids -s openapi.yaml -o operation-ids-overlay.yaml

このコマンドは仕様を分析し、次のような名前を変換するオーバーレイを生成します。

  • get_api_v1_users_list -> listUsers
  • post_api_v1_users_create -> createUser
ステップ 2：オーバーレイを確認して適用する

AI が生成したオーバーレイ（-o による出力）は、x-speakeasy-group と x-speakeasy-name-override を使って命名を改善します。

注：オーバーレイを手動で作成する場合は、このスキルではなく manage-openapi-overlays スキルを使用してください。

ステップ 3：オーバーレイを workflow.yaml に追加する
sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./operation-ids-overlay.yaml
ステップ 4：SDK を再生成する
speakeasy run --output console

エラー型の提案

suggest error-types コマンドは API を分析し、構造化されたエラーレスポンスを提案します。

speakeasy suggest error-types -s openapi.yaml

次の内容が提案されます。

  • 一般的な HTTP エラーコード（400、401、404、500）
  • API に適したカスタムエラースキーマ

オーバーレイとして出力します。

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

してはいけないこと

  • 外部で管理されている場合、ソース仕様の operationIds を直接変更しないでください。代わりにオーバーレイを使用してください。
  • グループを指定せずに get や post のような汎用名を使用しないでください。必ず x-speakeasy-name-override と x-speakeasy-group を組み合わせてください。
  • 作成後、生成されたオーバーレイを workflow.yaml に追加し忘れないでください。この手順を行わないと、生成される SDK の名前は変わりません。
  • 異なるグループ間で重複するオペレーション名を作成しないでください。各 {group}_{method} の組み合わせは一意である必要があります。

トラブルシューティング

エラー原因解決方法
"unauthorized"API キーがない、または無効ですSPEAKEASY_API_KEY 環境変数を設定するか、speakeasy auth login を実行してください
再生成後も名前が変わらないオーバーレイがワークフローに追加されていませんworkflow.yaml の overlays リストにオーバーレイを追加してください
提案が返されない仕様ですでに適切な名前が付いています対応は不要です。名前はすでに適切に構成されています
メソッド名が重複している類似したエンドポイントで同じ名前が使われています各エンドポイントに一意の x-speakeasy-name-override の値を設定してください
suggest の実行中にタイムアウトする仕様が非常に大きいですより小さなサブセットで実行するか、タイムアウトを延長してください

コメント

Markdown 対応