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 - 使用 overlays 自定义规范
• orchestrate-multi-repo-sdks - 每种语言使用独立仓库