Back to Details

orchestrate-multi-target-sdks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Orchestrate Multi-Target SDKs

编排多目标SDK

Generate SDKs for multiple languages or variants from a single repository using CLI commands.
通过CLI命令从单个仓库生成多语言或多变体的SDK。

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"
  • 从同一API规范生成多语言SDK
  • 从不同规范创建SDK变体（Azure、GCP、区域版等）
  • 搭建SDK Monorepo仓库
  • 用户提及：“生成多语言SDK”、“各语言专属SDK”、“多目标”

Quick Start: Multiple Languages

快速入门：多语言SDK

Always use CLI commands. Never create 
.speakeasy
directories manually.
bash
undefined
请始终使用CLI命令，切勿手动创建
.speakeasy
目录。
bash
undefined

Step 1: Initialize first target (creates .speakeasy/workflow.yaml)

步骤1：初始化首个目标（将创建.speakeasy/workflow.yaml）

speakeasy quickstart --skip-interactive --output console
-s openapi.yaml -t typescript -n "MySDK" -p "my-sdk"
speakeasy quickstart --skip-interactive --output console
-s openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

Step 2: Add more language targets using configure

步骤2：使用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
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

步骤3：生成所有SDK

speakeasy run --output console
undefined
speakeasy run --output console
undefined

CLI Reference

CLI参考

speakeasy configure sources

speakeasy configure sources

Add a new OpenAPI source to an existing workflow:
bash
speakeasy configure sources \
  --location ./openapi.yaml \
  --source-name my-api
向现有工作流添加新的OpenAPI源：
bash
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"

| Flag | Short | Description |
|------|-------|-------------|
| `--location` | `-l` | OpenAPI document location (file or URL) |
| `--source-name` | `-s` | Name for the source |
| `--auth-header` | | Authentication header name (optional) |
| `--output` | `-o` | Output path for compiled source (optional) |
| `--non-interactive` | | Force non-interactive mode |
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

speakeasy configure targets

Add a new SDK target to an existing workflow:
bash
speakeasy configure targets \
  --target-type typescript \
  --source my-api \
  --output ./sdks/typescript
向现有工作流添加新的SDK目标：
bash
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

| Flag | Short | Description |
|------|-------|-------------|
| `--target-type` | `-t` | Language: typescript, python, go, java, csharp, php, ruby, terraform |
| `--source` | `-s` | Name of source to generate from |
| `--target-name` | | Name for the target (defaults to target-type) |
| `--sdk-class-name` | | SDK class name (optional) |
| `--package-name` | | Package name (optional) |
| `--base-server-url` | | Base server URL (optional) |
| `--output` | `-o` | Output directory (optional) |
| `--non-interactive` | | Force non-interactive mode |
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` | 用于生成SDK的源名称 |
| `--target-name` | | 目标名称（默认值为target-type） |
| `--sdk-class-name` | | SDK类名（可选） |
| `--package-name` | | 包名（可选） |
| `--base-server-url` | | 基础服务器URL（可选） |
| `--output` | `-o` | 输出目录（可选） |
| `--non-interactive` | | 强制非交互模式 |

Example: Multi-Language SDKs

示例：多语言SDK

Single OpenAPI spec → TypeScript, Python, Go SDKs:
bash
undefined
单个OpenAPI规范 → TypeScript、Python、Go SDK：
bash
undefined

Initialize with first target

初始化首个目标

speakeasy quickstart --skip-interactive --output console
-s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk" -o ./sdks/typescript
speakeasy quickstart --skip-interactive --output console
-s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk" -o ./sdks/typescript

Add Python

添加Python目标

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

Add Go

添加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
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

生成所有SDK

speakeasy run --output console
undefined
speakeasy run --output console
undefined

Example: SDK Variants (Multiple Sources)

示例：SDK变体（多源）

Different OpenAPI specs → variant SDKs:
bash
undefined
不同OpenAPI规范 → 变体SDK：
bash
undefined

Initialize with main API

初始化主API目标

speakeasy quickstart --skip-interactive --output console
-s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk"
speakeasy quickstart --skip-interactive --output console
-s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

Add Azure variant source

添加Azure变体源

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

Add Azure target

添加Azure目标

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

生成所有SDK

speakeasy run --output console
undefined
speakeasy run --output console
undefined

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
my-api-sdks/
├── openapi.yaml              # 源规范文件
├── .speakeasy/
│   └── workflow.yaml         # 多目标配置文件（由CLI创建）
├── sdks/
│   ├── typescript/
│   │   ├── .speakeasy/
│   │   │   └── gen.yaml      # 由configure命令创建
│   │   └── src/
│   ├── python/
│   │   ├── .speakeasy/
│   │   │   └── gen.yaml
│   │   └── src/
│   └── go/
│       ├── .speakeasy/
│       │   └── gen.yaml
│       └── go.mod
└── .github/workflows/
    └── sdk_generation.yaml

Running Generation

执行生成操作

bash
undefined
bash
undefined

Generate all targets

生成所有目标SDK

speakeasy run --output console
speakeasy run --output console

Generate specific target only

仅生成指定目标SDK

speakeasy run -t typescript --output console speakeasy run -t python --output console
undefined
speakeasy run -t typescript --output console speakeasy run -t python --output console
undefined

CI Workflow

CI工作流

yaml
undefined
yaml
undefined

.github/workflows/sdk_generation.yaml

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

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
  • 请勿手动创建
    .speakeasy/
    目录     - 请使用
    speakeasy quickstart
    和
    speakeasy configure
    命令
  • 请勿直接编写
    workflow.yaml
    或
    gen.yaml
    文件     - 请使用CLI命令
  • 请勿在项目间复制
    .speakeasy/
    目录     - 每个项目都需要独立配置

Incorrect

错误示例

bash
undefined
bash
undefined

WRONG: Do not do this

错误：请勿这样操作

mkdir -p .speakeasy cat > .speakeasy/workflow.yaml << 'EOF' ... EOF
undefined
mkdir -p .speakeasy cat > .speakeasy/workflow.yaml << 'EOF' ... EOF
undefined

Correct

正确示例

bash
undefined
bash
undefined

RIGHT: Use CLI commands

正确：使用CLI命令

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
undefined
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
undefined

Troubleshooting

故障排除

IssueSolution
Wrong target generatedSpecify 
-t target-name
in 
speakeasy run
Source not foundRun 
speakeasy configure sources
to add it
Target not foundRun 
speakeasy configure targets
to add it
Config out of syncRun 
speakeasy run
to regenerate
问题解决方案
生成了错误的目标SDK在
speakeasy run
命令中指定
-t target-name
参数
找不到源执行
speakeasy configure sources
命令添加源
找不到目标执行
speakeasy configure targets
命令添加目标
配置不同步执行
speakeasy run
命令重新生成配置

After Making Changes

修改后的操作步骤

After adding sources or targets, regenerate:
bash
speakeasy run --output console
添加源或目标后，重新生成SDK：
bash
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:
bash
undefined
修改workflow.yaml或各目标的gen.yaml后，请提示用户重新生成SDK：
配置完成。是否现在使用
speakeasy run
重新生成SDK？
如果用户确认，执行：
bash
undefined

Generate all targets

生成所有目标SDK

speakeasy run --output console
speakeasy run --output console

Or generate a specific target

或生成指定目标SDK

speakeasy run -t <target-name> --output console

Changes to workflow.yaml and gen.yaml only take effect after regeneration.
speakeasy run -t <target-name> --output console

workflow.yaml和gen.yaml的修改仅在重新生成后生效。

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
  • start-new-sdk-project
    - 单目标SDK初始设置
  • configure-sdk-options
    - 各语言gen.yaml配置选项
  • manage-openapi-overlays
    - 使用覆盖层自定义规范
  • orchestrate-multi-repo-sdks
    - 按语言分仓管理SDK