Customize SDK Creation
The Speakeasy SDK pipeline uses sensible defaults to produce SDKs that most users will be happy with. However, there are several customizations that we recommend users make that will elevate your SDK users' experience. These customizations are made in two ways:
- Addition of
x-speakeasyexstensions to your OpenAPI spec.
- Edits to the
gen.yamlfile in your SDK repository.
The tables below contain the exhaustive list of available edits. Follow the links for more descriptive examples of how each extension and config can be used.
|Can be used globally to change method names or in-line to change the name of a method, prarmeter or class||Full Docs|
|Allows you to define custom namespaces. This field can be added 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 instead define the namespace for that method||Full Docs|
|Can be used to exclude certain methods from being included in your SDK.||Full Docs|
|Can be used to control generated enum members. It allows you to provide alternative names for each value in the enum field.||Full Docs|
|Can be used to enable retries globally or on a per-request basis. A backoff strategy is applied to specified status codes.||Full Docs|
|Used to customize offset-based or cursor-based pagination rules for each API operation.||Full Docs|
|A flag that can be added to a method to make it feature in your SDK's ||Full Docs|
|The OpenAPI specification doesn't allow example values for ||Full Docs|
|Use this extension to configure comments that only show up in the SDK for a single language.||Full Docs|
|Define parameters that can be configured globally on the main SDK instance and populated automatically for any operations that use them.||Full Docs|
|can be applied at the ||Full Docs|
|An extension to the OpenAPI spec to define an ID for each server in the servers array. This enable users to pick a server when instantiating the SDK||Full Docs|
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: "" sdkClassName: speakeasybar singleTagPerOp: false tagNamespacingDisabled: 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 maxMethodParams: 4 packageName: Speakeasy
gen.yaml file has several sections. The one that is important for SDK configuration is
management section is maintained by Speakeasy and should not be edited. The
features section should only be used if you need to pin your SDK's generation to a specific version of a Speakeasy feature. The final section will 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 generation config.
|Config Grouping||Config Field||Example||Description|
||Toggle to control whether Speakeasy generates comments as part of the code generation.|
||Toggle to control whether the generator should preference the summary over the description in documenting methods.|
||Use this field to declare your base server URL if the
||SDK class name for generation.|
||Use a single tag per operation.|
||Toggle to control whether the Speakeasy generator creates method namespaces based on your docuemnts.|