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:

  1. By adding x-speakeasy extensions to your OpenAPI spec.
  2. By editing the gen.yaml file 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

ExtensionDescriptionDocs
x-speakeasy-name-overrideUse it globally to change method names or in-line to change the name of a method, parameter, or class.Full Docs
x-speakeasy-groupAllows 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-ignoreExclude certain methods from your SDK with this extension.Full Docs
x-speakeasy-enumsUse this extension to control generated enum members by providing alternative names for each value in the enum field.Full Docs
x-speakeasy-retriesEnable retries globally or on a per-request basis. A backoff strategy is applied to specified status codes.Full Docs
x-speakeasy-paginationCustomize offset-based or cursor-based pagination rules for each API operation with this property.Full Docs
x-speakeasy-usage-exampleFeature a method in your SDK's README.md by adding this property to a method.Full Docs
x-speakeasy-exampleThe OpenAPI specification doesn't allow example values for securityscheme property. Using this extension overcomes this limitation.Full Docs
x-speakeasy-docsConfigure comments that only show up in the SDK for a single language.Full Docs
x-speakeasy-globalsDefine parameters that can be configured globally on the main SDK instance and populated automatically for any operations that use them.Full Docs
x-speakeasy-errorsApply this extension at the paths, path item, or operation level of the document to override the default error-handling behavior of the SDKsFull Docs
x-speakeasy-server-idEnable 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.

gen.yaml

configVersion: 1.0.0
management:
docChecksum: e77f226f321fb0ac7a96a5349eec64ed
docVersion: 1.0.0
speakeasyVersion: 1.82.3
generationVersion: 2.107.3
generation:
comments:
disableComments: false
omitDescriptionIfSummaryPresent: false
baseServerURL: "speakeasy.bar/public/api/"
sdkClassName: speakeasybar
singleTagPerOp: false
features:
typescript:
core: 2.87.1
examples: 2.81.2
flattening: 2.81.1
globalSecurity: 2.81.1
globalServerURLs: 2.82.0
groups: 2.81.1
nameOverrides: 2.81.1
retries: 2.82.0
typescript:
version: 1.12.0
author: Speakeasy
packageName: Speakeasy
maxMethodParams: 4