speakeasy

speakeasy copied to clipboard

Enterprise-Ready Developer Experience for your REST API

Launch production-quality SDKs, Terraform providers, docs, and more in minutes :rocket:

What is Speakeasy?

Speakeasy gives your users the developer experience that makes API integrations easy.

Don't put the burden of integration on your users. Take your APIs to market with best-in-class, enterprise-ready SDKs, Terraform providers, SDK docs, and more.

Key Features

• LLM Powered API Maintenance - Keep your API schema up to date and follow best practices with automatic maintenance powered by best-in-class LLMs. Try it out now in the CLI with speakeasy suggest or embed it into your GitHub workflow using our action.
• Production-Quality SDKs - Ergonomic, type-safe, and fault-tolerant client libraries built for production use cases with idiomatics optimized for each language. Embed additional capabilities like auth, retries, pagination, and more using spec-based extensions.
• Production-Quality Terraform Providers - Expose your API for infrastructure-as-code use cases with fully featured Terraform providers.
• SDK Docs - Markdown usage snippets for every single operation and model in your SDK. Export usage snippets and host them on a branded SDK and API docs site using our Docusaurus React plugin.
• Distribution to Package Managers - A complete pipeline for distributing your libraries to popular package managers like npm, PyPI, Maven, and Terraform Registry.
• Supports Open Standards - Speakeasy works with your existing API framework by supporting OpenAPI3.X and other open standards. Plug and play not rip and replace.

For upcoming features and bug fixes, check out our public roadmap.

What is the Speakeasy CLI?

The Speakeasy CLI is a tool for interacting with the Speakeasy platform that brings the functionality of Speakeasy into your development workflow.

You can run the Speakeasy CLI locally or in your CI/CD pipeline to validate your API specs, generate SDKs, and more. Looking to embed this into your GitHub CI/CD? Check out these docs instead.

Here are a few key functions of the CLI:

• generate - Generate idiomatic client SDKs from your API specs.
• validate - Validate the correctness of your API specs. The CLI has a built-in command to validate your spec for SDK readiness and post helpful error messages.
• suggest - Use an LLM to autocorrect your spec validation failures.
• merge - Work with your existing documentation workflows by merging your API specs into a single spec.
• auth - Authenticate with the platform and manage API keys.

For a complete list of commands check out our reference or type speakeasy and our interactive mode will take you through the available functions.

Design Choices

Each SDK generated by Speakeasy is idiomatic to the language it's generated for while sharing common patterns with SDKs for other languages to allow for switching between them. Using shared patterns also helps to keep the Speakeasy generation engine efficient while supporting many languages.

Here are some of the Speakeasy design decisions:

• Each SDK generally implements a base SDK class that contains the methods for each of the API endpoints defined in the OpenAPI document.
• Where possible, Speakeasy generates fully typed models from the OpenAPI document, separating models defined as components in the docs from models defined in line with operations.
• Based on the configuration in the OpenAPI document, Speakeasy annotates types using reflection metadata to determine how to serialize and deserialize them.
• To get SDKs to your end users quickly, Speakeasy generates full packages for each language that you should be able to publish to a package registry with little additional work. If you're interested in having a managed pipeline to your package manager, check out the Speakeasy Generation GitHub Action.

Want to learn more about the Speakeasy methodology? Take a look at how the Speakeasy SDK generator compares to OSS options.

If you're interested in generating managed GitHub repos for your SDKs or enterprise support, reach out to us or schedule a chat. We'd love to help you build out API DevEx.

If you're interested in having managed GitHub repos generated for your SDKs or enterprise support, reach out to us or schedule a chat. We'd love to help you build out API DevEx.

Speakeasy may capture metadata on usage of the Speakeasy CLI to better understand 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 outdated version. To update the CLI run:

speakeasy update

Alternatively, install the latest version via your package manager.

Getting Started With the Speakeasy CLI

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

speakeasy --help

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

Authenticating the Speakeasy CLI

The Speakeasy CLI depends on Speakeasy Platform APIs. Connect your Speakeasy CLI with the 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 your local network prevents you from accessing the login page prompted by the CLI, you can log in manually at app.speakeasyapi.dev, retrieve an API key, and populate a local environment variable named SPEAKEASY_API_KEY with the key.

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, defaults to go (available options: go, python, typescript, java)
  -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

Take a look at the Speakeasy getting started page for in-depth information.

Schema Validation

Note that you don't need to be logged in to the Speakeasy platform to validate your API schema.

Command:

speakeasy validate openapi [flags]

Options:

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

OpenAPI Usage

Note that you don't need to be logged in to the Speakeasy platform to view OpenAPI usage information.

Command:

Use the following command to return usage information for a given OpenAPI schema to a CSV. Usage information includes counts of OpenAPI features.

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

The tables below give an overview of what we support from OpenAPI.

✅ Server Configuration

⚠️ Path Parameters Serialization (path-parameters)

⚠️ Query Parameters Serialization (query-parameters & query)

✅ Request Headers (header)

⚠️ Request Body Serialization

⚠️ Response Body Deserialization

✅ Media-Type Patterns (media-types)

✅ Datatypes

✅ Miscellaneous

* Utility classes and functions to help with serialization and deserialization.

* Files needed for creating a fully compilable package that can be published to the relevant package manager without further changes.

Advanced Generation Features

• SDK Gen Configuration - Learn how to configure the SDK generator to your needs.
• Generated Comments - Learn how comments are generated from your OpenAPI document and how to customize them.
• Configuring the SDK with Server URLs - Learn how to configure the SDK to use different server URLs for different environments.
• Readme Generation - Learn how the SDK generates README.md files and how to control this.
• Using Custom HTTP Clients With the SDK - Learn how to provide a custom HTTP Client to the SDKs at runtime.
• Capturing Telemetry on SDK Usage - Learn how you can capture telemetry to get an understanding of how your SDKs are being used.
• Automated SDK Generation - Use our GitHub Action and Workflows to set up CI/CD for generating and publishing your SDKs.
• Override Generated Names - Speakeasy uses your OpenAPI schema to infer names for class types, methods, and parameters. However, you can override these names to tailor the generated SDK to your preferences.
• Add Retries to Your SDKs - The generator supports the ability to generate SDKs that will automatically retry requests that fail due to network errors or any configured HTTP status code.

Getting Support

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

Usage

speakeasy [flags]

Options

  -h, --help   help for speakeasy

Sub Commands

• speakeasy api - Access the Speakeasy API via the CLI
• speakeasy auth - Authenticate the CLI
• speakeasy generate - Generate Client SDKs and Terraform Providers
• speakeasy validate - Validate OpenAPI documents

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, c#, swift, ruby, terraform) - Validating OpenAPI specs - Interacting with the Speakeasy API to create and manage your API workspaces - Generating OpenAPI specs from your API traffic - Generating Postman collections from OpenAPI Specs

Usage

speakeasy [flags]

Options

  -h, --help              help for speakeasy
      --logLevel string   the log level (available options: [info, warn, error]) (default "info")

Sub Commands

• speakeasy ask - Starts a conversation with Speakeasy trained AI
• speakeasy auth - Authenticate the CLI
• speakeasy bump - Bumps the version of a Speakeasy Generation Target
• speakeasy clean - Speakeasy clean can be used to clean up cache, stale temp folders, and old CLI binaries.
• speakeasy configure - Configure your Speakeasy SDK Setup.
• speakeasy generate - One off Generations for client SDKs and more
• speakeasy lint - Lint/Validate OpenAPI documents and Speakeasy configuration files
• speakeasy merge - Merge multiple OpenAPI documents into a single document
• speakeasy openapi - Utilities for working with OpenAPI documents
• speakeasy overlay - Work with OpenAPI Overlays
• speakeasy quickstart - Guided setup to help you create a new SDK in minutes.
• speakeasy run - generate an SDK, compile OpenAPI sources, and much more from a workflow.yaml file
• speakeasy suggest - Automatically improve your OpenAPI document with an LLM
• speakeasy tag - Add tags to a given revision of your API. Specific to a registry namespace
• speakeasy update - Update the Speakeasy CLI to the latest version