SDK Creation Overview
Stages of availability
✅ GA: The interface is stable and all the available features are fully supported. Support subscribes to SLAs.
🔵 Beta: The interface is mostly stable but may not support all features (see the language page for details). Support subscribes to SLAs.
🏗️ Alpha: The interface is not yet stable and all feature support is experimental. Support does not subscribe to SLAs.
Please see here for a more indepth guide on our language maturity levels.
Prerequisites
- An installation of Speakeasy CLI. You can use Homebrew to install the Speakeasy CLI by running:
brew install speakeasy-api/homebrew-tap/speakeasy
Script (macOS and Linux)
curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh
Chocolatey (Windows)
choco install speakeasy
Manual Installation
Download the latest release for your platform from the releases page (opens in a new tab) then extract the binary and add it to your path.
- Submit your API spec in one of our supported formats:
| Spec Format | Supported |
|---|---|
| OpenAPI 3.0 | ✅ |
| OpenAPI 3.1 | ✅ |
| JSON Schema | ✅ |
| Postman Collections | 🔜 |
TIP
If your spec is in an unsupported format, use one of the following tools to convert it:
- Swagger 2.0 -> OpenAPI 3.0 (opens in a new tab): go to Edit > Convert to OpenAPI 3.0
- Postman -> OpenAPI 3.0 (opens in a new tab)
Interactive SDK Generation With CLI Quickstart
If you are generating an SDK for the first time with Speakeasy, we recommend working through speakeasy quickstart. Please install the Speakeasy CLI first by running brew install speakeasy-api/tap/speakeasy.
To kick off the quickstart process, open your terminal and enter the following command:
speakeasy quickstart
This command initiates an interactive session to guide you through generating your SDK. You'll be prompted to create a workspace on our dashboard (opens in a new tab) if you haven't already.
You will be prompted to select the language for your SDK:
Enter other required parameters specific to your SDK as prompted:
After receiving all the necessary input, Speakeasy will validate your specifications and generate the SDK. The process will execute speakeasy run to validate, generate, compile, and set up your SDK. If successful, you'll see a confirmation message along with details of the generated SDK:
If you make further changes to your OpenAPI document or SDK configuration, re-run the speakeasy run command to regenerate your SDK.
Finally, consider setting up your SDK on GitHub for a fully managed experience. See our GitHub setup guide here.
Traditional SDK Generation
Experienced users, or those looking to integrate SDK generation into scripts, may prefer a non-interactive approach by specifying all the necessary parameters in one command. Please note this method requires stringing together your workflow to validate, generate, compile, and publish your SDK.
In most cases, we recommend executing speakeasy quickstart and run as shown in the quickstart section above.
speakeasy generate sdk --out <output_directory> --schema <specification_path_or_url> [options]
Required Parameters:
--out: Destination for the generated SDK.--schema: Path or URL to your API spec.
Additional Options
-y, --auto-yes auto answer yes to all prompts -d, --debug enable writing debug files with broken code -H, --header string header key to use if authentication is required for downloading schema from remote URL -h, --help help for sdk -i, --installationURL string the language specific installation URL for installation instructions if the SDK is not published to a package manager -l, --lang string language to generate sdk for (available options: [csharp, go, java, php, python, ruby, swift, terraform, typescript, unity]) (default "go") -p, --published whether the SDK is published to a package manager or not, determines the type of installation instructions to generate -r, --repo string the repository URL for the SDK, if the published (-p) flag isn't used this will be used to generate installation instructions -b, --repo-subdir string the subdirectory of the repository where the SDK is located in the repo, helps with documentation generation --token string token value to use if authentication is required for downloading schema from remote URL
Next Step: Customize Your SDK
Generating SDKs is the first step but there are several optimizations you can make to improve the quality of your SDKs. Check out the following guide on customizing your SDKs.