Categorygithub.com/speakeasy-api/speakeasy
repositorypackage
0.22.1
Repository: https://github.com/speakeasy-api/speakeasy.git
Documentation: pkg.go.dev
Overview
Dependencies
1
Dependents
0

# Packages

No description provided by the author

# README

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-1-941c72f269

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 OpenAPI3.X specs:
    • Live: Go, Python3, Typescript(Node), Java
    • Coming soon: Terraform, Rust, Ruby, C# and more languages on upon request!
  • Validating the correctness of OpenAPI3 specs. The CLI has a built in command to validate your spec and post helpful error messages.
  • Authenticating with the platform and managing API keys.

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 capabale 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 a spec.
  • Where possible we generate fully typed models from the OpenAPI document and seperate 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

brew install speakeasy-api/homebrew-tap/speakeasy

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