orchestrate-multi-target-sdks（编排多目标 SDK）

Orchestrate Multi-Target SDKs

Generate SDKs for multiple languages or variants from a single repository using CLI commands.

When to Use

• Generating SDKs for multiple languages from the same API spec
• Creating SDK variants (Azure, GCP, regional) from different specs
• Setting up an SDK monorepo
• User says: "generate SDKs for multiple languages", "SDK for each language", "multi-target"

Quick Start: Multiple Languages

Always use CLI commands. Never create .speakeasy directories manually.

# 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 Reference

speakeasy configure sources

Add a new OpenAPI source to an existing workflow:

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"

speakeasy configure targets

Add a new SDK target to an existing workflow:

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

Example: Multi-Language SDKs

Single OpenAPI spec → TypeScript, Python, Go SDKs:

# 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

Example: SDK Variants (Multiple Sources)

Different OpenAPI specs → variant SDKs:

# 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

Repository Structure

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

Running Generation

# Generate all targets
speakeasy run --output console

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

CI Workflow

# .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 }}

What NOT to Do

• Do NOT create .speakeasy/ directories manually - Use speakeasy quickstart and speakeasy configure
• Do NOT write workflow.yaml or gen.yaml files directly - Use CLI commands
• Do NOT copy .speakeasy/ directories between projects - Each needs its own config

Incorrect

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

Correct

# 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

Troubleshooting

After Making Changes

After adding sources or targets, regenerate:

speakeasy run --output console

After Making Changes

After modifying workflow.yaml or per-target gen.yaml, prompt the user to regenerate the SDK(s):

Configuration complete. Would you like to regenerate the SDK(s) now with speakeasy run?

If the user confirms, run:

# Generate all targets
speakeasy run --output console

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

Changes to workflow.yaml and gen.yaml only take effect after regeneration.

Related Skills

• start-new-sdk-project - Initial SDK setup for single target
• configure-sdk-options - Language-specific gen.yaml options
• manage-openapi-overlays - Spec customization with overlays
• orchestrate-multi-repo-sdks - Separate repository per language