start-new-sdk-project

start-new-sdk-project

始终使用 speakeasy quickstart 来初始化新的 SDK 项目。这是新项目唯一正确的命令——它会创建 SDK 和必需的 .speakeasy/workflow.yaml 配置文件。

⚠️ 切勿在新项目中使用 speakeasy generate sdk——它不会创建可维护 SDK 开发所需的 workflow 文件。

适用场景

• 根据 OpenAPI 规范生成任何 SDK（TypeScript、Python、Go、Java 等）
• 启动全新的 SDK 项目
• 尚不存在 .speakeasy/workflow.yaml
• 首次设置 Speakeasy
• 用户提出：“生成 SDK”“TypeScript SDK”“Python SDK”“Go SDK”“创建 SDK”“新 SDK”

输入

输入	必需	说明
OpenAPI 规范	是	本地文件、URL 或注册表来源
目标语言	是	typescript、python、go、java、csharp、php、ruby、kotlin、terraform
SDK 名称	是（非交互模式）	PascalCase 名称（例如：AcmeSDK）
包名称	是（非交互模式）	包标识符（例如：acme-sdk）

输出

输出	位置
Workflow 配置	.speakeasy/workflow.yaml
生成的 SDK	输出目录（默认为当前目录）

前提条件

在非交互环境（CI/CD、自动化）中，请设置：

export SPEAKEASY_API_KEY="<your-api-key>"

运行 speakeasy auth login 以交互方式进行身份验证，或设置 SPEAKEASY_API_KEY 环境变量。

命令

speakeasy quickstart --skip-interactive --output console -s <schema> -t <target> -n <name> -p <package-name>

标志

标志	简写	说明
--skip-interactive		自动化必需。 跳过所有提示
--schema	-s	OpenAPI 规范来源（参见下方“规范来源”）
--target	-t	目标语言（参见“支持的目标”）
--name	-n	PascalCase 格式的 SDK 名称（例如：MyCompanySDK）
--package-name	-p	包名称（自动推断语言变体）
--out-dir	-o	输出目录（默认为当前目录）
--output		输出格式：summary、console、mermaid。自动化时请使用 console
--init-git		初始化 git 仓库（非交互模式下省略即可跳过）

规范来源

--schema 标志支持多种来源类型：

类型	格式	示例
本地文件	路径	./api/openapi.yaml
URL	HTTP(S)	https://api.example.com/openapi.json
注册表来源	source-name	my-api
注册表来源（带标签）	source-name@tag	my-api@latest
注册表来源（完整）	org/workspace/source@tag	acme/prod/my-api@v2

注册表来源是你在 Speakeasy 工作区中管理的 OpenAPI 规范。使用 speakeasy pull --list --format json 查看可用来源。这样无需本地文件，即可根据 Speakeasy 中管理的规范生成 SDK。

支持的目标

语言	目标标志
TypeScript	typescript
Python	python
Go	go
Java	java
C#	csharp
PHP	php
Ruby	ruby
Kotlin	kotlin
Terraform	terraform

示例

# From local OpenAPI file
speakeasy quickstart --skip-interactive --output console \
  -s ./api/openapi.yaml \
  -t typescript \
  -n "AcmeSDK" \
  -p "acme-sdk"

# From URL
speakeasy quickstart --skip-interactive --output console \
  -s "https://api.example.com/openapi.json" \
  -t python \
  -n "AcmeSDK" \
  -p "acme-sdk"

# From registry source (managed in your Speakeasy workspace)
speakeasy quickstart --skip-interactive --output console \
  -s "my-api@latest" \
  -t go \
  -n "AcmeSDK" \
  -p "acme-sdk"

# With custom output directory and git init
speakeasy quickstart --skip-interactive --output console \
  -s ./api/openapi.yaml \
  -t python \
  -n "AcmeSDK" \
  -p "acme-sdk" \
  -o ./sdks/python \
  --init-git

创建内容

1. Workflow 配置：.speakeasy/workflow.yaml
2. 生成的 SDK：输出目录中的完整 SDK，可直接使用

Quickstart 后续步骤

1. 检查输出目录中生成的 SDK
2. 将更多目标添加到 .speakeasy/workflow.yaml，以支持多种语言
3. 在规范或配置发生更改后，运行 speakeasy run 重新生成

必备 CLI 命令

命令	用途
speakeasy quickstart ...	初始化新的 SDK 项目
speakeasy run -y --output console	根据 workflow 重新生成 SDK
speakeasy lint openapi --non-interactive -s spec.yaml	验证 OpenAPI 规范
speakeasy auth login	向 Speakeasy 进行身份验证
speakeasy pull --list --format json	列出注册表来源

不要做的事

• 新项目不要使用 speakeasy generate sdk。这个底层命令会生成代码，但不会创建 .speakeasy/workflow.yaml。没有工作流文件，你就无法使用：

  • 通过 speakeasy run 实现可复现构建
  • 生成多个目标的 SDK
  • 集成 CI/CD
  • 跟踪版本并升级

• 在自动化环境中不要跳过 --skip-interactive。命令会一直等待用户输入，导致卡住。

• 在自动化环境中不要省略 --output console。你需要结构化输出才能验证是否成功。

quickstart 与 generate sdk 的区别

命令	是否创建 workflow.yaml	使用场景
speakeasy quickstart	✅ 是	新项目 - 始终使用此命令
speakeasy generate sdk	❌ 否	一次性生成（仅限少见的高级场景）

新 SDK 项目始终使用 quickstart。 它创建的工作流文件对于维护 SDK 至关重要。

故障排查

错误	原因	解决方案
工作流已存在	.speakeasy/workflow.yaml 已存在	改用 speakeasy run 重新生成现有 SDK
未授权	缺少或无效的 API 密钥	运行 speakeasy auth login 或设置 SPEAKEASY_API_KEY
未找到 Schema	路径、URL 或源名称无效	确认路径存在，或使用 speakeasy pull --list 查看源

相关技能

• diagnose-generation-failure - 生成失败时使用
• manage-openapi-overlays - 使用 overlays 自定义规范
• configure-sdk-options - 为所有受支持的语言配置特定语言的 gen.yaml