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:

  1. Addition of x-speakeasy exstensions to your OpenAPI spec.
  2. Edits to the gen.yaml file 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.

x-speakeasy Extensions

x-speakeasy-extensionDescriptionDocs
x-speakeasy-name-overrideCan be used globally to change method names or in-line to change the name of a method, prarmeter or classFull Docs
x-speakeasy-groupAllows 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 methodFull Docs
x-speakeasy-ignoreCan be used to exclude certain methods from being included in your SDK.Full Docs
x-speakeasy-enumsCan be used to control generated enum members. It allows you to provide alternative names for each value in the enum field.Full Docs
x-speakeasy-retriesCan be used to enable retries globally or on a per-request basis. A backoff strategy is applied to specified status codes.Full Docs
x-speakeasy-paginationUsed to customize offset-based or cursor-based pagination rules for each API operation.Full Docs
x-speakeasy-usage-exampleA flag that can be added to a method to make it feature in your SDK's README.mdFull Docs
x-speakeasy-exampleThe OpenAPI specification doesn't allow example values for securityschemes. Use this exstension to overcome the limitation.Full Docs
x-speakeasy-docsUse this extension to configure 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-errorscan be applied 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-idAn 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 SDKFull Docs

gen.yaml Configuration

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

The gen.yaml file has several sections. The one that is important for SDK configuration is generation. The 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.

Generation Config

Config Grouping Config Field Example Description
comments disableComments false Toggle to control whether Speakeasy generates comments as part of the code generation.
comments omitDescriptionIfSummaryPresent false Toggle to control whether the generator should preference the summary over the description in documenting methods.
baseServerURL "speakeasy.bar/public/api/" Use this field to declare your base server URL if the servers field is absent from your spec.
sdkClassName Speakeasy SDK class name for generation.
singleTagPerOp false Use a single tag per operation.
tagNamespacingDisabled false Toggle to control whether the Speakeasy generator creates method namespaces based on your docuemnts.