Customize SDK Creation
The Speakeasy SDK pipeline uses sensible defaults to produce SDKs, which most users will be happy with.
However, there are several customizations that we recommend to elevate your SDK users' experience. These customizations are made in two ways:
- By tweaking the OpenAPI spec.
- By adding
x-speakeasyextensions to your OpenAPI spec. - By editing the
gen.yamlfile in your SDK repository.
The following tables contain an exhaustive list of available x-speakeasy extensions and gen.yaml file configurations. Follow the links for more descriptive examples of how each extension and configuration can be used.
List of Speakeasy Extensions
| Extension | Description | Docs |
|---|---|---|
x-speakeasy-name-override | Use it globally to change method names or in-line to change the name of a method, parameter, or class. | Full Docs |
x-speakeasy-group | Allows you to define custom namespaces when adding this property to any operation in your OpenAPI spec. If added, the tags for that method will be ignored and the value of x-speakeasy-group will define the namespace for that method instead. | Full Docs |
x-speakeasy-ignore | Exclude certain methods from your SDK with this extension. | Full Docs |
x-speakeasy-enums | Use this extension to control generated enum members by providing alternative names for each value in the enum field. | Full Docs |
x-speakeasy-retries | Enable retries globally or on a per-request basis. A backoff strategy is applied to specified status codes. | Full Docs |
x-speakeasy-pagination | Customize offset-based or cursor-based pagination rules for each API operation with this property. | Full Docs |
x-speakeasy-usage-example | Feature a method in your SDK's README.md by adding this property to a method. | Full Docs |
x-speakeasy-example | The OpenAPI specification doesn't allow example values for securityscheme property. Using this extension overcomes this limitation. | Full Docs |
x-speakeasy-docs | Configure comments that only show up in the SDK for a single language. | Full Docs |
x-speakeasy-globals | Define parameters that can be configured globally on the main SDK instance and populated automatically for any operations that use them. | Full Docs |
x-speakeasy-globals-hidden | Define parameters that can be configured globally on the main SDK instance but are not shown in the matching method's signature. | Full Docs |
x-speakeasy-errors | Apply this extension at the paths, path item, or operation level of the document to override the default error-handling behavior of the SDKs | Full Docs |
x-speakeasy-error-message | Used to mark a field in an error reponse as the field containing the error message to use. | Full Docs |
x-speakeasy-server-id | Enable users to pick a server when instantiating the SDK. Use this extension to define an ID for each server in the servers array to the OpenAPI spec. | Full Docs |
x-speakeasy-deprecation-message | Allows you to add a message to deprecated operations, parameters and schemas. | Full Docs |
x-speakeasy-deprecation-replacement | Allows you to specify an alternate operation to use in place of a deprecated operation. | Full Docs |
x-speakeasy-type-override | Use this to override the type of a schema to force it to be handled as an any type to accept arbitrary data. | Full Docs |
x-speakeasy-max-method-params | Allows you to set the maximum number of parameters that can be passed to a method. If the number of parameters exceeds this value, a request object will be used instead. | Full Docs |
x-speakeasy-extension-rewrite | Allows you to map speakeasy extensions to other extensions you may already have that match functionality. | See below |
Using x-speakeasy-extension-rewrite you can map any extension from the wider OpenAPI ecosystem or another vendor to the equivalent Speakeasy extension. This allows you to use your existing OpenAPI spec without needing to make changes to it if possible.
openapi: 3.1.0info: title: My API version: 1.0.0x-speakeasy-extension-rewrite: x-speakeasy-enums: x-enum-varnames # Maps x-enum-varnames used by the OSS generator to x-speakeasy-enums which has the same functionality
The gen.yaml File Configuration
Speakeasy SDKs can be further configured through the use of a configuration file called gen.yaml. This file will typically live in the .speakeasy folder at the root of your SDKs location.
The gen.yaml file contains both language specific and language agnostic configurations that can control the shape of your SDK, outside what is possible via your OpenAPI document.
For more information on the configuration options available in the gen.yaml file, please refer to our gen.yaml reference.
Let's take a closer look at the gen.yaml configs you may want to edit.
Generation
sdkClassName this field controls the main class name of your SDK.
maintainOpenAPIOrder if set to true, parameters, properties and the order the document is iterated through will match the order in your OpenAPI document otherwise it will be sorted alphabetically.
usageSnippets.optionalPropertyRendering controls how optional properties are rendered in the SDK. The options are withExample, always & never.
useClassNamesForArrayFields if set to true, array fields will be named after the classes they contain.
Language Config
This section (typescript in the example above) controls configurations that are specific to your language target and its package.
version the version number given to the package being produced. We will automatically update this, but if you modify it we will use this new version number on the next generation.
packageName determines what the package will be called. The format of this will need to match the package manager that you're publishing to. Please see publish your SDK.
maxMethodParams if set, Speakeasy will in-line request parameters for methods that have up to that number of parameters. Methods that require more will need a request object to be passed in.
responseFormat determines how the response is formatted for example returning the referenced type directly without wrapping it in a envelope class. The options are flat, envelope-http & envelope.