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"

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

Add Python

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

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"

Add Azure variant source

添加Azure变体源

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

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

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

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:

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

故障排除

Issue	Solution
Wrong target generated	Specify `-t target-name` in `speakeasy run`
Source not found	Run `speakeasy configure sources` to add it
Target not found	Run `speakeasy configure targets` to add it
Config out of sync	Run `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

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的修改仅在重新生成后生效。

orchestrate-multi-target-sdks

Original

Translation

Orchestrate Multi-Target SDKs

编排多目标SDK

When to Use

适用场景

Quick Start: Multiple Languages

快速入门：多语言SDK

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

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

Step 2: Add more language targets using configure

步骤2：使用configure命令添加更多语言目标

Step 3: Generate all SDKs

步骤3：生成所有SDK

CLI Reference

CLI参考

speakeasy configure sources

speakeasy configure sources

With authentication header

带认证头的情况

speakeasy configure targets

speakeasy configure targets

With all options

包含所有选项的情况

Example: Multi-Language SDKs

示例：多语言SDK

Initialize with first target

初始化首个目标

Add Python

添加Python目标

Add Go

添加Go目标

Generate all

生成所有SDK

Example: SDK Variants (Multiple Sources)

示例：SDK变体（多源）

Initialize with main API

初始化主API目标

Add Azure variant source

添加Azure变体源

Add Azure target

添加Azure目标

Generate all

生成所有SDK

Repository Structure

仓库结构

Running Generation

执行生成操作

Generate all targets

生成所有目标SDK

Generate specific target only

仅生成指定目标SDK

CI Workflow

CI工作流

.github/workflows/sdk_generation.yaml

.github/workflows/sdk_generation.yaml

What NOT to Do

注意事项（禁止操作）

Incorrect

错误示例

WRONG: Do not do this

错误：请勿这样操作

Correct

正确示例

RIGHT: Use CLI commands

正确：使用CLI命令

Troubleshooting

故障排除

After Making Changes

修改后的操作步骤

After Making Changes

修改后的操作步骤

Generate all targets

生成所有目标SDK

Or generate a specific target

或生成指定目标SDK

Related Skills

相关技能

`speakeasy configure sources`

`speakeasy configure sources`

`speakeasy configure targets`

`speakeasy configure targets`