start-new-sdk-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

start-new-sdk-project

启动新SDK项目

Always use
speakeasy quickstart
to initialize a new SDK project. This is the ONLY correct command for new projects - it creates both the SDK and the essential

.speakeasy/workflow.yaml

configuration file.

⚠️ Never use
speakeasy generate sdk
for new projects - it does not create the workflow file needed for maintainable SDK development.

**请始终使用

speakeasy quickstart

**来初始化新的SDK项目。这是创建新项目的唯一正确命令——它会同时生成SDK和必不可少的

.speakeasy/workflow.yaml

配置文件。

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

When to Use

使用场景

Generating any SDK from an OpenAPI spec (TypeScript, Python, Go, Java, etc.)
Starting a brand new SDK project
No
```
.speakeasy/workflow.yaml
```
exists yet
First-time Speakeasy setup
User says: "generate SDK", "TypeScript SDK", "Python SDK", "Go SDK", "create SDK", "new SDK"

从OpenAPI规范生成任意类型的SDK（TypeScript、Python、Go、Java等）
启动全新的SDK项目
尚未存在
```
.speakeasy/workflow.yaml
```
文件
首次进行Speakeasy配置
用户提及：“generate SDK”、“TypeScript SDK”、“Python SDK”、“Go SDK”、“create SDK”、“new SDK”

Inputs

输入参数

Input	Required	Description
OpenAPI spec	Yes	Local file, URL, or registry source
Target language	Yes	typescript, python, go, java, csharp, php, ruby, kotlin, terraform
SDK name	Yes (non-interactive)	PascalCase name (e.g., `AcmeSDK` )
Package name	Yes (non-interactive)	Package identifier (e.g., `acme-sdk` )

输入项	是否必填	描述
OpenAPI规范	是	本地文件、URL或注册表源
目标语言	是	typescript、python、go、java、csharp、php、ruby、kotlin、terraform
SDK名称	是（非交互式模式）	大驼峰命名（例如： `AcmeSDK` ）
包名称	是（非交互式模式）	包标识符（例如： `acme-sdk` ）

Outputs

输出内容

Output	Location
Workflow config	`.speakeasy/workflow.yaml`
Generated SDK	Output directory (default: current dir)

输出项	位置
工作流配置	`.speakeasy/workflow.yaml`
生成的SDK	输出目录（默认：当前目录）

Prerequisites

前置条件

For non-interactive environments (CI/CD, automation), set:

bash

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

Run

speakeasy auth login

to authenticate interactively, or set the

SPEAKEASY_API_KEY

environment variable.

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

bash

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

运行

speakeasy auth login

进行交互式认证，或设置

SPEAKEASY_API_KEY

环境变量。

Command

命令

bash

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

bash

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

Flags

命令参数

Flag	Short	Description
`--skip-interactive`		Required for automation. Skips all prompts
`--schema`	`-s`	OpenAPI spec source (see Schema Sources below)
`--target`	`-t`	Target language (see Supported Targets)
`--name`	`-n`	SDK name in PascalCase (e.g., `MyCompanySDK` )
`--package-name`	`-p`	Package name (language variants auto-inferred)
`--out-dir`	`-o`	Output directory (default: current dir)
`--output`		Output format: `summary` , `console` , `mermaid` . Use `console` for automation
`--init-git`		Initialize git repo (omit to skip in non-interactive mode)

参数	简写	描述
`--skip-interactive`		自动化环境必填。跳过所有交互提示
`--schema`	`-s`	OpenAPI规范源（见下方规范源类型）
`--target`	`-t`	目标语言（见支持的目标语言）
`--name`	`-n`	SDK的大驼峰名称（例如： `MyCompanySDK` ）
`--package-name`	`-p`	包名称（语言变体将自动推断）
`--out-dir`	`-o`	输出目录（默认：当前目录）
`--output`		输出格式： `summary` 、 `console` 、 `mermaid` 。自动化环境请使用 `console`
`--init-git`		初始化git仓库（非交互式模式下可省略以跳过）

Schema Sources

规范源类型

The

--schema

flag accepts multiple source types:

Type	Format	Example
Local file	Path	`./api/openapi.yaml`
URL	HTTP(S)	`https://api.example.com/openapi.json`
Registry source	`source-name`	`my-api`
Registry source (tagged)	`source-name@tag`	`my-api@latest`
Registry source (full)	`org/workspace/source@tag`	`acme/prod/my-api@v2`

Registry sources are OpenAPI specs you manage in your Speakeasy workspace. Use

speakeasy pull --list --format json

to see available sources. This lets you generate SDKs from specs managed in Speakeasy without needing local files.

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

Supported Targets

支持的目标语言

Language	Target Flag
TypeScript	`typescript`
Python	`python`
Go	`go`
Java	`java`
C#	`csharp`
PHP	`php`
Ruby	`ruby`
Kotlin	`kotlin`
Terraform	`terraform`

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

Example

示例

bash

undefined

bash

undefined

From local OpenAPI file

从本地OpenAPI文件生成

speakeasy quickstart --skip-interactive --output console
-s ./api/openapi.yaml
-t typescript
-n "AcmeSDK"
-p "acme-sdk"

From URL

从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工作区中管理）

speakeasy quickstart --skip-interactive --output console
-s "my-api@latest"
-t go
-n "AcmeSDK"
-p "acme-sdk"

With custom output directory and git init

指定自定义输出目录并初始化git

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

undefined

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

undefined

What It Creates

生成的内容

Workflow configuration:
```
.speakeasy/workflow.yaml
```
Generated SDK: Full SDK in the output directory, ready to use

工作流配置：
```
.speakeasy/workflow.yaml
```
生成的SDK：输出目录中的完整SDK，可直接使用

Next Steps After Quickstart

Quickstart后的后续步骤

Review the generated SDK in the output directory
Add more targets to
```
.speakeasy/workflow.yaml
```
for multi-language support
Run
```
speakeasy run
```
to regenerate after spec or config changes

查看输出目录中生成的SDK
在
```
.speakeasy/workflow.yaml
```
中添加更多目标语言以支持多语言SDK
当规范或配置发生变化时，运行
```
speakeasy run
```
重新生成SDK

Essential CLI Commands

必备CLI命令

Command	Purpose
`speakeasy quickstart ...`	Initialize new SDK project
`speakeasy run -y --output console`	Regenerate SDK from workflow
`speakeasy lint openapi --non-interactive -s spec.yaml`	Validate OpenAPI spec
`speakeasy auth login`	Authenticate with Speakeasy
`speakeasy pull --list --format json`	List registry sources

命令	用途
`speakeasy quickstart ...`	初始化新SDK项目
`speakeasy run -y --output console`	根据工作流重新生成SDK
`speakeasy lint openapi --non-interactive -s spec.yaml`	验证OpenAPI规范
`speakeasy auth login`	登录Speakeasy进行认证
`speakeasy pull --list --format json`	列出注册表源

What NOT to Do

切勿执行的操作

Do NOT use
speakeasy generate sdk
for new projects. This low-level command generates code but does NOT create
```
.speakeasy/workflow.yaml
```
. Without a workflow file, you lose:
- Reproducible builds via
```
speakeasy run
```
- Multi-target SDK generation
- CI/CD integration
- Version tracking and upgrade paths
Do NOT skip
--skip-interactive
in automated environments. The command will hang waiting for user input.
Do NOT omit
--output console
in automated environments. You need structured output to verify success.

切勿在新项目中使用
speakeasy generate sdk
。这个底层命令仅生成代码，但不会创建
```
.speakeasy/workflow.yaml
```
文件。没有工作流文件，你将失去：
- 通过
```
speakeasy run
```
  实现可重复构建
- 多目标SDK生成能力
- CI/CD集成
- 版本跟踪和升级路径
在自动化环境中切勿跳过
--skip-interactive
参数。命令会因等待用户输入而挂起。
在自动化环境中切勿省略
--output console
参数。你需要结构化输出来验证操作是否成功。

quickstart vs generate sdk

Command	Creates workflow.yaml	Use case
`speakeasy quickstart`	✅ Yes	New projects - Always use this
`speakeasy generate sdk`	❌ No	One-off generation (rare, advanced use only)

Always use
quickstart
for new SDK projects. The workflow file it creates is essential for maintainable SDK development.

命令	是否创建workflow.yaml	使用场景
`speakeasy quickstart`	✅ 是	新项目——请始终使用此命令
`speakeasy generate sdk`	❌ 否	一次性生成（罕见，仅适用于高级场景）

请始终为新SDK项目使用
quickstart
命令。它创建的工作流文件对于可维护的SDK开发至关重要。

Troubleshooting

故障排除

Error	Cause	Solution
Workflow already exists	`.speakeasy/workflow.yaml` already present	Run `speakeasy run` to regenerate the existing SDK instead
Unauthorized	Missing or invalid API key	Run `speakeasy auth login` or set `SPEAKEASY_API_KEY`
Schema not found	Invalid path, URL, or source name	Verify path exists or use `speakeasy pull --list` for sources

错误	原因	解决方案
工作流已存在	已存在 `.speakeasy/workflow.yaml` 文件	运行 `speakeasy run` 重新生成现有SDK
未授权	API密钥缺失或无效	运行 `speakeasy auth login` 或设置 `SPEAKEASY_API_KEY`
未找到规范	路径、URL或源名称无效	验证路径是否存在，或使用 `speakeasy pull --list` 查看可用源

start-new-sdk-project

Original

Translation

start-new-sdk-project

启动新SDK项目

When to Use

使用场景

Inputs

输入参数

Outputs

输出内容

Prerequisites

前置条件

Command

命令

Flags

命令参数

Schema Sources

规范源类型

Supported Targets

支持的目标语言

Example

示例

From local OpenAPI file

从本地OpenAPI文件生成

From URL

从URL生成

From registry source (managed in your Speakeasy workspace)

从注册表源生成（在你的Speakeasy工作区中管理）

With custom output directory and git init

指定自定义输出目录并初始化git

What It Creates

生成的内容

Next Steps After Quickstart

Quickstart后的后续步骤

Essential CLI Commands

必备CLI命令

What NOT to Do

切勿执行的操作

quickstart vs generate sdk

quickstart vs generate sdk

Troubleshooting

故障排除

Related Skills

相关技能