Customization basics

The Speakeasy SDK pipeline uses sensible defaults to generate SDKs, but various customizations can improve the user experience. Customizations can be applied using the following methods:

  1. Modifying the OpenAPI document.
  2. Adding x-speakeasy extensions to the OpenAPI document.
  3. Editing the gen.yaml file in the SDK repository.

1. Modifying the OpenAPI document

The OpenAPI document is the foundation of SDK generation. Modifications to the OpenAPI document influence the structure, naming conventions, and functionality of generated SDKs.

Learn more about OpenAPI in the reference documentation.

Modifying the OpenAPI document with overlays

Speakeasy supports OpenAPI overlays, which you can use to customize and extend existing OpenAPI documents without directly modifying them. Overlays are especially useful for applying different configurations or updates to the specification for various environments or SDKs without altering the base OpenAPI document.

Overlays work by referencing and extending parts of the base OpenAPI document. They can be used to add, override, or remove elements such as paths, schemas, parameters, or security configurations.

Screenshot showing a speakeasy extension in VS code editor.

Learn more about overlays.

2. Using x-speakeasy extensions

Proprietary Speakeasy extensions provide fine-tuned control over the SDK, enabling you to modify behaviors like retries, pagination, error handling, and other advanced SDK features.

Add Speakeasy extensions to the OpenAPI document.

Screenshot showing a speakeasy extension in VS code editor.

For a complete list of available extensions, see the Speakeasy extensions reference.

3. Editing the gen.yaml file

Further customize Speakeasy-generated SDKs by editing the gen.yaml file, typically located in the .speakeasy folder at the root of the SDK. This configuration file contains both language-agnostic and language-specific settings, offering more control over the structure and behavior of the SDK beyond what the OpenAPI document provides.

Edit the gen.yaml file to modify elements like class names, method parameters, and response formatting.

Screenshot showing the gen.yaml in VS code editor.

For a complete list of available options, refer to the gen.yaml reference.