orchestrate-multi-target-sdks

マルチターゲット SDK のオーケストレーション

CLI コマンドを使用して、単一のリポジトリから複数の言語またはバリアント向けの SDK を生成します。

使用するタイミング

• 同じ API 仕様から複数の言語向け SDK を生成する場合
• 異なる仕様から SDK のバリアント（Azure、GCP、リージョン別）を作成する場合
• SDK モノレポをセットアップする場合
• ユーザーが「複数の言語向けに SDK を生成」「各言語向けの SDK」「マルチターゲット」と言った場合

クイックスタート：複数の言語

必ず CLI コマンドを使用してください。 .speakeasy ディレクトリを手動で作成しないでください。

# Step 1: Initialize first target (creates .speakeasy/workflow.yaml)
speakeasy quickstart --skip-interactive --output console \
  -s openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

# Step 2: Add more language targets using configure
speakeasy configure targets \
  --target-type python \
  --source my-source \
  --output ./sdks/python

speakeasy configure targets \
  --target-type go \
  --source my-source \
  --output ./sdks/go

# Step 3: Generate all SDKs
speakeasy run --output console

CLI リファレンス

speakeasy configure sources

既存のワークフローに新しい OpenAPI ソースを追加します。

speakeasy configure sources \
  --location ./openapi.yaml \
  --source-name my-api

# With authentication header
speakeasy configure sources \
  --location https://api.example.com/openapi.yaml \
  --source-name my-api \
  --auth-header "Authorization"

フラグ	短縮形	説明
--location	-l	OpenAPI ドキュメントの場所（ファイルまたは URL）
--source-name	-s	ソース名
--auth-header		認証ヘッダー名（任意）
--output	-o	コンパイルされたソースの出力先（任意）
--non-interactive		非対話モードを強制

speakeasy configure targets

既存のワークフローに新しい SDK ターゲットを追加します。

speakeasy configure targets \
  --target-type typescript \
  --source my-api \
  --output ./sdks/typescript

# With all options
speakeasy configure targets \
  --target-type go \
  --source my-api \
  --target-name my-go-sdk \
  --sdk-class-name MyAPI \
  --package-name github.com/myorg/myapi-go \
  --output ./sdks/go

フラグ	短縮形	説明
--target-type	-t	言語：typescript、python、go、java、csharp、php、ruby、terraform
--source	-s	生成元のソース名
--target-name		ターゲット名（デフォルトは target-type）
--sdk-class-name		SDK クラス名（任意）
--package-name		パッケージ名（任意）
--base-server-url		ベースサーバー URL（任意）
--output	-o	出力ディレクトリ（任意）
--non-interactive		非対話モードを強制

例：多言語 SDK

単一の OpenAPI 仕様 → TypeScript、Python、Go の SDK：

# Initialize with first target
speakeasy quickstart --skip-interactive --output console \
  -s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk" -o ./sdks/typescript

# Add Python
speakeasy configure targets \
  --target-type python \
  --source my-source \
  --sdk-class-name MySDK \
  --package-name my-sdk \
  --output ./sdks/python

# Add Go
speakeasy configure targets \
  --target-type go \
  --source my-source \
  --sdk-class-name MySDK \
  --package-name github.com/myorg/my-sdk-go \
  --output ./sdks/go

# Generate all
speakeasy run --output console

例：SDK バリアント（複数ソース）

異なる OpenAPI 仕様 → バリアント SDK：

# Initialize with main API
speakeasy quickstart --skip-interactive --output console \
  -s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

# Add Azure variant source
speakeasy configure sources \
  --location ./openapi-azure.yaml \
  --source-name azure-api

# Add Azure target
speakeasy configure targets \
  --target-type typescript \
  --source azure-api \
  --target-name typescript-azure \
  --sdk-class-name MySDKAzure \
  --package-name "@myorg/my-sdk-azure" \
  --output ./packages/azure

# Generate all
speakeasy run --output console

リポジトリ構成

my-api-sdks/
├── openapi.yaml              # Source spec
├── .speakeasy/
│   └── workflow.yaml         # Multi-target config (created by CLI)
├── sdks/
│   ├── typescript/
│   │   ├── .speakeasy/
│   │   │   └── gen.yaml      # Created by configure
│   │   └── src/
│   ├── python/
│   │   ├── .speakeasy/
│   │   │   └── gen.yaml
│   │   └── src/
│   └── go/
│       ├── .speakeasy/
│       │   └── gen.yaml
│       └── go.mod
└── .github/workflows/
    └── sdk_generation.yaml

生成の実行

# Generate all targets
speakeasy run --output console

# Generate specific target only
speakeasy run -t typescript --output console
speakeasy run -t python --output console

CI ワークフロー

# .github/workflows/sdk_generation.yaml
name: Generate SDKs
on:
  push:
    branches: [main]
    paths: ['openapi.yaml']
  workflow_dispatch:

jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
    with:
      mode: pr
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

やってはいけないこと

• .speakeasy/ ディレクトリを手動で作成しないでください - speakeasy quickstart と speakeasy configure を使用してください
• workflow.yaml ファイルや gen.yaml ファイルを直接作成しないでください - CLI コマンドを使用してください
• .speakeasy/ ディレクトリをプロジェクト間でコピーしないでください - 各プロジェクトに独自の設定が必要です

誤り

# WRONG: Do not do this
mkdir -p .speakeasy
cat > .speakeasy/workflow.yaml << 'EOF'
...
EOF

正しい方法

# RIGHT: Use CLI commands
speakeasy quickstart --skip-interactive --output console \
  -s openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

speakeasy configure targets --target-type python --source my-source

トラブルシューティング

問題	解決策
誤ったターゲットが生成された	speakeasy run で -t target-name を指定してください
ソースが見つからない	speakeasy configure sources を実行して追加してください
ターゲットが見つからない	speakeasy configure targets を実行して追加してください
設定が同期していない	speakeasy run を実行して再生成してください

変更後

ソースまたはターゲットを追加した後、再生成してください。

speakeasy run --output console

変更後

workflow.yaml またはターゲットごとの gen.yaml を変更した後、SDK を再生成するようにユーザーに確認してください。

設定が完了しました。 speakeasy run で SDK を今すぐ再生成しますか？

ユーザーが確認した場合は、次を実行してください。

# Generate all targets
speakeasy run --output console

# Or generate a specific target
speakeasy run -t <target-name> --output console

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

関連スキル

• start-new-sdk-project - 単一ターゲット向けの SDK 初期セットアップ
• configure-sdk-options - 言語固有の gen.yaml オプション
• manage-openapi-overlays - オーバーレイによる仕様のカスタマイズ
• orchestrate-multi-repo-sdks - 言語ごとに別のリポジトリを使用