start-new-sdk-project

start-new-sdk-project

新しい SDK プロジェクトを初期化する場合は、必ず speakeasy quickstart を使用してください。 新しいプロジェクトで使用できる正しいコマンドはこれだけです。このコマンドは、SDK と、不可欠な .speakeasy/workflow.yaml 設定ファイルの両方を作成します。

⚠️ 新しいプロジェクトで speakeasy generate sdk を使用しないでください。 保守しやすい SDK 開発に必要なワークフローファイルが作成されません。

使用する場面

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

出力

出力	場所
ワークフロー設定	.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. ワークフロー設定：.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	ワークフローから 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 を設定してください
スキーマが見つかりません	パス、URL、またはソース名が無効です	パスが存在することを確認するか、ソースを確認するには speakeasy pull --list を使用してください

関連スキル

• diagnose-generation-failure - 生成に失敗した場合
• manage-openapi-overlays - オーバーレイで仕様をカスタマイズ
• configure-sdk-options - サポートされているすべての言語向けの言語固有の gen.yaml 設定