Changelog #12: SDKs and Our March of Progress

Changes to the Speakeasy platform - December 01, 2022.

SDK generators are attractive because they’re easy. Hand Rolling SDKs requires time and broad language expertise. The downside has always been that generated SDKs sacrifice developer experience. Generated SDKs feel like they exist so that someone could tick a box and claim they offered SDKs, even though those SDKs would never be something a developer would want to use.

We’re determined to make an SDK generator that is not only easy to use, but makes SDKs that are great for your users. Since we rolled out the beta of our SDK generator, we’ve continued to add features that add the type of finishing touches that take an SDK from usable to enjoyable.

New Features

Easy OpenAPI Extension: Multiple Servers - OpenAPI is great, but it has some glaring holes. One is that, when there are multiple servers, it doesn’t provide a strongly typed way to define which server to use by default. Speakeasy provides an extension to the OpenAPI spec that allows you to define an ID for each server in the Servers array. This can be done using the x-speakeasy-server-id property on the server object. Read more about how in our documentation.

openapi: 3.0.3
info:
  title: Example
  version: 0.0.1
servers:
  - url: https://prod.example.com # Used as the default URL by the SDK
    description: Our production environment
    x-speakeasy-server-id: prod
  - url: https://sandbox.example.com
    description: Our sandbox environment
    x-speakeasy-server-id: sandbox

Servers are just the start. We’re building out extensions for retries and pagination and are looking for customers interested in being alphas users (opens in a new tab).

Readmes & Code Comments - SDKs are more than just the functions in the library. They’re also the business context in which they exist. That’s why the Speakeasy generator creates a Readme with install instructions and usage examples, and generates code comments & usage snippets based on your OpenAPI operation’s descriptions. Read more about how in our documentation: Readme & Code comments.

Custom HTTP Client Support - We know that SDKs don’t exist in a vacuum. That’s why our SDKs are built to be optionally used with a custom HTTP Client. This allows you to use HTTP Clients that are setup to use proxies, provide custom telemetry or be preconfigured with global headers or any additional configuration. Read more about how, in our documentation.

Small Improvements

Google Login - Users now have the option of logging in with their google account in addition to github. More auth providers to come!