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 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 x-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-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-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 |
The gen.yaml File Configuration
The gen.yaml file has several sections. The generation section is important for SDK configuration. We'll take a closer look at the generation configuration next.
The one that is important for SDK configuration is generation. The management and features section is maintained by Speakeasy and should not be edited. The final section contains be specific to the generation language (i.e. typescript) and is for configuring your SDK's publishing. For more information, see package publishing.
Let's take a closer look at the gen.yaml configs you may want to edit.
Comments
disableComments field controls Speakeasy's generation of comments as part of code generation.
omitDescriptionIfSummaryPresent controls whether the generator should prefer the summary over the description in documenting methods.
Generation
baseServerURL this field declares your base server URL if the servers field is absent from your spec.
sdkClassName this field controls the SDK class name used in generation.
singleTagPerOp if your methods are associated with multiple tags, this field can be used to only use the first tag when building namespaces.
Language Config
This section 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 you have the option to edit it.
author the author name that will be displayed on the package.
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 parameters object to be passed in.