/speakeasy

Speakeasy CLI makes validating API specs and generating idiomatic SDKs easy !

Primary LanguageGoOtherNOASSERTION

The Speakeasy CLI - Generate Client SDKs Like a Human Wrote Them

181640742-31ab234a-3b39-432e-b899-21037596b360

Speakeasy is the fastest way to ship developer experience for your APIs.

ezgif com-video-to-gif (1)

What is Speakeasy ?

Speakeasy gives your users the DevEx that makes API integrations easy. Don't put the burden of integration on your users. Take your APIs to market with best in class sdks and a complete self-service experience from shipping great sdks to managing keys, logs and more.

What is the Speakeasy CLI ?

This CLI is a tool for interacting with the Speakeasy platform - the CLI brings the functionality of Speakeasy into your development workflow. It can be run locally or in your CI/CD pipeline to validate your API specs, generate SDKs and more.

Current functions of the CLI include:

  • Generating idiomatic client SDKs from OpenAPI 3.X specs:
    • Live: Go, Python3, Typescript(Node), Java, PHP, Ruby, Terraform
    • Coming soon: Rust, C#, Swift and more languages upon request!
  • Validating the correctness of OpenAPI 3.X specs. The CLI has a built in command to validate your spec and post helpful error messages.
  • Merging OpenAPI 3.X specs. The CLI can merge multiple OpenAPI 3.X specs into a single spec.
  • Authenticating with the platform and managing API keys.
  • Using the Speakeasy API to manage your integration.

Design Choices

All the SDKs we generate are designed to be as idiomatic to the language they are generated for as possible while being similar enough to each other to allow some familiarity between them, but also to allow for an efficient generation engine that is capable of supporting many languages. Some of the design decisions we made are listed below:

  • Each of the SDKs generally implement a base SDK class that contains the methods for each of the API endpoints defined in the OpenAPI document.
  • Where possible we generate fully typed models from the OpenAPI document and separate those models defined as components in the docs and those that are defined inline with operations.
  • We use reflection metadata where possible to annotate types with the required metadata needed to determine how to serialize and deserialize them, based on the configuration in the OpenAPI document.
  • We generate full packages for each language that should be able to be published to a package registry with little additional work, to get them in your end-users hands as quickly as possible. If you're interested in having a managed pipeline to your package manager check out our Github action.

Want to learn more about our methodology? Here is a blog post to learn more about our generators as compared to the OSS options. If you're interested in having managed Github repos generated for your SDKs or enterprise support reach out to us here or come chat with us. We'd love to help you build out API dev ex.

We may capture telemetry on usage of the CLI to better understand API (OpenAPI) features so that we can build better code generators and other tools over time

Installation

Homebrew (MacOS and Linux)

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, extract and add the binary to your path.

Keeping up to date

The CLI will warn you if you're running an out of date version. To update the CLI run:

speakeasy update

or install the latest version via your package manager.

Getting Started with the Speakeasy CLI

Once you installed the Speakeasy CLI, you can verify it's working by running:

speakeasy --help

See the docs for more information on how to get started with the Speakeasy CLI.

Authenticating Speakeasy CLI

Speakeasy CLI depends on Speakeasy Platform APIs. Connect your Speakeasy CLI with Speakeasy Platform by running:

speakeasy auth login

You'll be redirected to a login URL to select an existing workspace or create a new workspace on the platform. If you're local network prevents accessing the login page prompted by the CLI you can login manually at app.speakeasyapi.dev, retrieve an API key and populate a local environment variable named SPEAKEASY_API_KEY with the key.

Screenshot 2023-01-29 at 23 12 05

SDK Generation

Command:

speakeasy generate sdk [flags]

Options:

  -b, --baseurl string   base URL for the api (only required if OpenAPI spec doesn't specify root server URLs
  -d, --debug            enable writing debug files with broken code
  -h, --help             help for sdk
  -l, --lang string      language to generate sdk for (available options: [go, python, typescript, java]) (default "go")
  -o, --out string       path to the output directory
  -s, --schema string    path to the openapi schema
  -y, --auto-yes string  auto answer yes to all prompts

For in depth documentation please see our docs.

Schema Validation

Note, Schema validation doesn't require logging in to the Speakeasy Platform.

Command:

speakeasy validate openapi [flags]

Options:

  -h, --help            help for openapi
  -s, --schema string   path to the openapi schema

OpenAPI Usage

Note, OpenAPI usage doesn't require logging in to the Speakeasy Platform.

The following command outputs usage information containing counts of OpenAPI features for a given OpenAPI schema to a CSV.

Command:

speakeasy usage [flags]

Options:

  -d, --debug         enable writing debug files with broken code
  -f, --file string   Path to file to generate usage information for
  -h, --help          help for usage
  -o, --out string    Path to output file

OpenAPI Support

Advanced Generation Features

Getting Support

If you need support using Speakeasy CLI, please contact us via email, slack or file a Github issue and we'll respond ASAP !

Usage

speakeasy [flags]

Options

  -h, --help   help for speakeasy

Sub Commands

CLI

speakeasy

The speakeasy cli tool provides access to the speakeasyapi.dev toolchain

Details

A cli tool for interacting with the Speakeasy https://www.speakeasyapi.dev/ platform and its various functions including: - Generating Client SDKs from OpenAPI specs (go, python, typescript, java, php + more coming soon) - Validating OpenAPI specs - Interacting with the Speakeasy API to create and manage your API workspaces - Generating OpenAPI specs from your API traffic (coming soon) - Generating Postman collections from OpenAPI Specs (coming soon)

Usage

speakeasy [flags]

Options

  -h, --help   help for speakeasy

Sub Commands