configure-sdk-options

SDK オプションを設定する

既存の Speakeasy SDK の gen.yaml オプションを設定します。TypeScript、Python、Go、Java、C#、PHP、Ruby に対応しています。

新しい SDK プロジェクトの場合：代わりに start-new-sdk-project スキルを使用してください。このスキルは既存の SDK の設定に使用します。

言語別ガイド

設定の詳細については、言語別ガイドを参照してください。

言語	ガイド	主な機能
TypeScript	content/languages/typescript.md	Zod による検証、React Query、スタンドアロン関数、デュアルモジュール形式
Python	content/languages/python.md	Pydantic モデル、非同期モード（both/split）、uv/poetry のサポート
Go	content/languages/go.md	レスポンス形式、インターフェース生成、K8s 統合
Java	content/languages/java.md	ビルダーパターン、Gradle のカスタマイズ、Maven Central への公開
C#	content/languages/csharp.md	Async/await、キャンセルトークン、DI 統合、NuGet
PHP	content/languages/php.md	Laravel 統合、Guzzle の設定、Packagist への公開
Ruby	content/languages/ruby.md	Sorbet の型付け、Rails 統合、RubyGems への公開

これらのガイドには、詳細な設定オプション、コード例、フレームワーク統合、公開手順が記載されています。

使用するタイミング

• 既存 SDK の言語固有の gen.yaml オプションを設定する場合
• SDK フック、非同期パターン、または公開を設定する場合
• アプリケーションコードでランタイムの動作（再試行、タイムアウト、サーバー選択）を設定する場合
• ユーザーが「SDK を設定」「gen.yaml オプション」「SDK の設定」「ランタイムのオーバーライド」「呼び出しごとの設定」と言った場合
• ユーザーが Zod、Pydantic、NuGet、PyPI、npm、Maven Central、Packagist、RubyGems について質問した場合

入力

入力	必須	説明
既存の SDK	はい	.speakeasy/workflow.yaml がすでに作成されている SDK
対象言語	はい	TypeScript、Python、Go、Java、C#、PHP、または Ruby

出力

出力	説明
更新された gen.yaml	言語固有の設定
フックファイル	有効にした場合のカスタムフック

前提条件

.speakeasy/workflow.yaml を含む既存の SDK が必要です。ない場合は、次を実行してください。

speakeasy quickstart --skip-interactive --output console \
  -s openapi.yaml -t <language> -n "MySDK" -p "<package-name>"

共通設定（すべての言語）

これらのオプションは、gen.yaml 内のすべての SDK ターゲットに適用されます。

<language>:
  version: 1.0.0
  packageName: "my-sdk"

  # Method signatures
  maxMethodParams: 4              # Params before request object
  flatteningOrder: parameters-first

  # Error handling
  responseFormat: flat            # or "envelope" (Go)
  clientServerStatusCodesAsErrors: true

TypeScript の設定

typescript:
  version: 1.0.0
  packageName: "@myorg/my-sdk"
  moduleFormat: dual              # esm, commonjs, or dual
  zodVersion: v4-mini             # v3, v4, or v4-mini
  enableCustomCodeRegions: true   # For custom code
  enableReactQuery: true          # React Query hooks

機能	説明
Zod による検証	すべてのモデルで自動的に行われます
ツリーシェイキング	moduleFormat: dual とスタンドアロン関数を使用します
JSR への公開	jsr.json を作成し、deno publish を実行します
npm への公開	標準の npm publish

ツリーシェイキングのためのスタンドアロン関数：

import { TodoCore } from "my-sdk/core.js";
import { todosCreate } from "my-sdk/funcs/todosCreate.js";
const sdk = new TodoCore({ apiKey: "..." });

Python の設定

python:
  version: 1.0.0
  packageName: "my-sdk"
  asyncMode: both                 # both or split
  packageManager: uv              # uv or poetry
  envVarPrefix: ""                # Prefix for env config

機能	説明
Pydantic モデル	すべてのモデルで自動的に使用されます
非同期モード both	sdk.method() と sdk.method_async()
非同期モード split	SDK() と AsyncSDK() のコンストラクター
PyPI への公開	uv publish または poetry publish

非同期パターン：

# asyncMode: both (default)
result = sdk.users.list()           # sync
result = await sdk.users.list_async() # async

# asyncMode: split
sdk = MySDK()                       # sync only
async_sdk = AsyncMySDK()            # async only

Go の設定

go:
  version: 0.1.0
  packageName: github.com/myorg/my-sdk
  maxMethodParams: 2
  methodArguments: require-security-and-request
  responseFormat: envelope
  flattenGlobalSecurity: true

機能	説明
インターフェース	ifacemaker を使用して生成します
モック	mockery を使用して生成します
K8s 統合	kubebuilder マーカーを追加し、controller-gen を実行します

テスト用のインターフェース生成：

go install github.com/vburenin/ifacemaker@latest
go install github.com/vektra/mockery/v2@latest
ifacemaker --file consumers.go --struct Consumers --iface ConsumersSDK --output consumers_i.go
mockery

Java の設定

java:
  version: 1.0.0
  groupID: com.myorg
  artifactID: my-sdk
  packageName: com.myorg.mysdk
  methodArguments: require-security-and-request

機能	説明
ビルダーパターン	すべてのクラスで自動的に使用できます
ビルドのカスタマイズ	build-extras.gradle（保持されます）を使用します
Maven Central	./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository

クライアントの使用方法：

MySdk sdk = MySdk.builder()
    .security(Security.builder().apiKey("key").build())
    .build();

C# の設定

csharp:
  version: 1.0.0
  packageName: MyOrg.MySDK
  dotnetVersion: "6.0"
  baseErrorName: MySDKException

機能	備考
Async/await	すべての操作はデフォルトで非同期です
SSE ストリーミング	EventStream<T> をサポートします
NuGet への公開	dotnet pack -c Release && dotnet nuget push

キャンセルに対応した非同期処理：

var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = await sdk.Users.ListAsync(cancellationToken: cts.Token);

PHP の設定

php:
  version: 1.0.0
  packageName: myorg/my-sdk
  namespace: MyOrg\MySDK

機能	備考
PHP 8.2+	必要な最小バージョン
Guzzle	HTTP クライアント（タイムアウトを設定可能）
Packagist	リリースにタグを付け、Packagist.org に登録します

トークン更新用のセキュリティコールバック：

$sdk = MySDK\MySDK::builder()
    ->setSecuritySource(fn() => getTokenFromCache() ?? refreshToken())
    ->build();

Ruby の設定

ruby:
  version: 1.0.0
  packageName: my-sdk
  module: MySdk
  typingStrategy: sorbet          # sorbet or none

機能	備考
Sorbet による型付け	任意。typingStrategy: sorbet で有効にします
Faraday	HTTP クライアント
RubyGems	gem build && gem push

SDK フック（すべての言語）

enableCustomCodeRegions: true を指定してカスタムフックを有効にします。フックファイルは再生成時に保持されます。

言語	フックの場所
TypeScript	src/hooks/
Python	src/<pkg>/_hooks/
Go	internal/hooks/
Java	src/main/java/.../hooks/
C#	src/.../Hooks/
PHP	src/Hooks/
Ruby	lib/.../sdk_hooks/

フックの実装の詳細については、customize-sdk-hooks スキルを参照してください。

ランタイムのオーバーライド

ランタイムの動作は、SDK のインスタンス化時または呼び出しごとに設定できます。これらの設定は gen.yaml のデフォルトを上書きします。

サーバーの選択

OpenAPI 仕様でサーバー ID を定義し、ランタイムに選択します。

# OpenAPI spec
servers:
  - url: https://api.example.com
    x-speakeasy-server-id: production
  - url: https://sandbox.example.com
    x-speakeasy-server-id: sandbox

言語	SDK コンストラクター	カスタム URL
TypeScript	new SDK({ server: "sandbox" })	new SDK({ serverURL: "..." })
Python	SDK(server="sandbox")	SDK(server_url="...")
Go	SDK.New(SDK.WithServer("sandbox"))	SDK.WithServerURL("...")

リトライのオーバーライド

呼び出しごとにリトライの動作を上書きします（仕様のデフォルトは x-speakeasy-retries で設定します）。

TypeScript：

const res = await sdk.payments.create({ amount: 1000 }, {
  retries: {
    strategy: "backoff",
    backoff: { initialInterval: 1000, maxInterval: 30000, maxElapsedTime: 120000, exponent: 2.0 },
    retryConnectionErrors: true,
  },
});

Python：

from sdk.utils import BackoffStrategy, RetryConfig
res = sdk.payments.create(amount=1000, retries=RetryConfig("backoff",
    backoff=BackoffStrategy(1000, 30000, 120000, 2.0), retry_connection_errors=True))

Go：

res, err := sdk.Payments.Create(ctx, req, operations.WithRetries(retry.Config{
    Strategy: "backoff", Backoff: &retry.BackoffStrategy{
        InitialInterval: 1000, MaxInterval: 30000, MaxElapsedTime: 120000, Exponent: 2.0},
    RetryConnectionErrors: true}))

タイムアウトのオーバーライド

SDK コンストラクターでグローバルタイムアウトを設定するか、呼び出しごとに設定します。

言語	グローバル	呼び出しごと
TypeScript	new SDK({ timeoutMs: 30000 })	sdk.op({}, { timeoutMs: 60000 })
Python	SDK(timeout_ms=30000)	sdk.op(timeout_ms=60000)
Go	SDK.WithTimeoutMs(30000)	operations.WithTimeoutMs(60000)

ページネーションの使用方法

仕様で x-speakeasy-pagination が設定されている場合、SDK はページネーションヘルパーを自動生成します。

// Auto-iterate all pages
for await (const user of await sdk.users.list({ limit: 50 })) {
  console.log(user.name);
}

// Manual pagination
let page = await sdk.users.list({ limit: 50 });
while (page) {
  for (const user of page.data) { console.log(user.name); }
  page = await page.next();
}

判断の指針

状況	対応
ツリーシェイキングが必要（TS）	moduleFormat: dual を設定し、スタンドアロン関数を使用します
非同期／同期が必要（Python）	asyncMode: both を設定します（デフォルト）
非同期クライアントを分離する必要がある（Python）	asyncMode: split を設定します
テスト用のインターフェースが必要（Go）	ifacemaker + mockery を使用します
カスタムビルド設定が必要（Java）	build-extras.gradle を編集します
ランタイムでリトライを上書きする必要がある	呼び出しごとのオプションで retries 設定を渡します
ランタイムでタイムアウトを上書きする必要がある	コンストラクターまたは呼び出しごとに timeoutMs を設定します
サーバーを切り替える必要がある	仕様で x-speakeasy-server-id を使用し、ランタイムに選択します

やってはいけないこと

• このスキルを SDK の初回生成に使用しないでください。start-new-sdk-project を使用してください
• カスタムコード領域の外にある生成済みファイルを編集しないでください
• 保持対象ディレクトリ（hooks、extra）に含まれない src/ 内のファイルを変更しないでください

トラブルシューティング

言語	問題	解決策
TypeScript	バンドルサイズが大きすぎる	スタンドアロン関数を使用します
Python	非同期ページネーションがブロックされる	fixFlags.asyncPaginationSep2025: true を有効にします
Go	インターフェースが生成されない	構造体がエクスポートされている（大文字で始まる）ことを確認します
Java	Gradle の同期に失敗する	./gradlew --refresh-dependencies を実行します
C#	非同期デッドロック	.Result ではなく await を使用します
PHP	PHP バージョンエラー	PHP 8.2 以降が必要です
Ruby	Sorbet エラー	bundle exec tapioca gems を実行します
すべて	リトライが機能しない	x-speakeasy-retries がドキュメントのルートまたはオペレーションレベルにあることを確認します
すべて	サーバー ID が認識されない	各サーバーエントリーに x-speakeasy-server-id を追加します
すべて	ページネーションの next() が未定義	リストオペレーションに x-speakeasy-pagination を追加します

変更後の作業

gen.yaml の設定を変更した後、SDK を再生成するようユーザーにプロンプトを表示してください。

設定が完了しました。 speakeasy run を実行して SDK を再生成しますか？

ユーザーが確認した場合は、次を実行します。

speakeasy run --output console

gen.yaml の変更は、再生成後にのみ反映されます。

関連スキル

• start-new-sdk-project - SDK の初期生成
• customize-sdk-hooks - フック実装の詳細
• manage-openapi-overlays - 仕様のカスタマイズ