The gen.yaml File Reference
TIP
For most use cases, we recommend interacting with the Speakeasy gen.yaml file using the speakeasy configure command, which has subcommands to configure your sources, targets, GitHub setup, and package publishing. All new targets created using speakeasy quickstart automatically have workflow files created in the .speakeasy/ folder in the root of their target directory.
For editing the gen.yaml file manually, the Speakeasy VS Code extension (opens in a new tab) provides syntax highlighting, autocompletion,
and linting for OpenAPI documents and other supported file types.
The gen.yaml file has several sections.
- The
generationsection is important for SDK configuration. - The
managementandfeaturessections are maintained by Speakeasy. You should not edit these sections. - The final section is for configuring SDK publishing and contains configuration specific to the generation language. For more information, see package publishing.
Let's take a closer look at the gen.yaml configs you may want to edit.
Full Reference
Generation
configVersion
The currently supported version of the Speakeasy gen.yaml configuration file is 2.0.0. Older versions will be automatically upgraded when encountered.
generation
The generation section of the configuration supports configuration that is relevant to all SDK targets. If a value isn't configured here and it has a default value then that value will be added automatically on the next generation.
sdkClassName
Defines the class name of the main imported class in the generated SDK.
maintainOpenAPIOrder
Determines whether to maintain the order of parameters, properties, operations, etc. as they appear in the OpenAPI spec. If set to false, these elements are sorted alphabetically.
usageSnippets
optionalPropertyRendering: Options include always, never, and withExample, which renders optional properties only when an example is present in the OpenAPI spec.
devContainers
Enables or disables the use of development containers and specifies the schema path.
useClassNamesForArrayFields
When set to true, array fields use class names instead of the child schema type.
fixes
Includes specific fixes or features to be applied during SDK generation to avoid breaking changes.
nameResolutionDec2023: Disabling not recommended. Enables changes introduced in December 2023 for improved name resolution, defaults to true for new SDKs. For older SDKs setting true is recommended, but will be a breaking change.
parameterOrderingFeb2024: Disabling not recommended. Enables changes introduced in February 2024 to respect the order of parameters in the OpenAPI document where possible, defaults to true for new SDKs. For older SDKs setting true is recommended, but will be a breaking change.
requestResponseComponentNamesFeb2024: Disabling not recommended. Enables changes introduced in February 2024 to use the name of parent request/response components where possible, defaults to true for new SDKs. For older SDKs setting true is recommended, but will be a breaking change.
auth
OAuth2ClientCredentialsEnabled: Enables the generation of code for handling OAuth 2.0 client credentials for authentication, where possible. Enterprise license only
baseServerUrl
This field is used to declare your base server URL. It overrides the servers field in your spec if present, or provides a server URL if the servers field is absent.
configVersion
The currently supported version of the Speakeasy gen.yaml configuration file is 2.0.0. Older versions will be automatically upgraded when encountered.
generation
The generation section of the configuration supports configuration that is relevant to all SDK targets. If a value isn't configured here and it has a default value then that value will be added automatically on the next generation.
maintainOpenAPIOrder
Determines whether to maintain the order of parameters, properties, operations, etc. as they appear in the OpenAPI spec. If set to false, these elements are sorted alphabetically.
usageSnippets
optionalPropertyRendering: Options include always, never, and withExample, which renders optional properties only when an example is present in the OpenAPI spec.
useClassNamesForArrayFields
When set to true, array fields use class names instead of the child schema type.
fixes
Includes specific fixes or features to be applied during SDK generation to avoid breaking changes.
nameResolutionDec2023: Disabling not recommended. Enables changes introduced in December 2023 for improved name resolution, defaults to true for new SDKs. For older SDKs setting true is recommended, but will be a breaking change.
parameterOrderingFeb2024: Disabling not recommended. Enables changes introduced in February 2024 to respect the order of parameters in the OpenAPI document where possible, defaults to true for new SDKs. For older SDKs setting true is recommended, but will be a breaking change.
requestResponseComponentNamesFeb2024: Disabling not recommended. Enables changes introduced in February 2024 to use the name of parent request/response components where possible, defaults to true for new SDKs. For older SDKs setting true is recommended, but will be a breaking change.
Language Configs
version
The version of an SDK is automatically bumped by Speakeasy. If you specify a version, Speakeasy will use that version on the next generation instead of automatically bumping it.
additionalDependencies
Specifies additional dependencies to be included in the generated package.json dependencies section.
Supports setting dependencies, devDependencies, and peerDependencies.
Each section is a simple object that maps an npm package name to a version range. See the npm docs (opens in a new tab) for more details.
author
Specify the name that will be displayed in the package manager's author field.
clientServerStatusCodesAsErrors
Set to false to treat error code responses as a standard response object. This overrides the default behavior of the SDK treating 4XX or 5XX responses as returning error objects.
flattenGlobalSecurity
Enable the security object to be passed inline during the SDK instantiation. Recommend setting to true.
imports
The imports field in the SDK generation configuration enables customization of model import paths within the SDK. This allows for tailored organization of models in directories, enhancing how they are imported and referenced by users, and providing flexibility in managing SDK structure.
inputModelSuffix
Specifies the suffix to append to the name of models that get split for requests and responses based on readOnly and writeOnly schema properties.
maxMethodParams
Set a threshold on the number of parameters that can be passed inline to an SDK method. Methods that require more parameters to be passed in will require a request parameters object to be passed in. When maxMethodParams is set to 0, all SDK methods require a request parameters object for passing arguments, eliminating inline parameter passing.
This can be overridden by using the x-speakeasy-max-method-params extension in the OpenAPI spec, see here for full details.
outputModelSuffix
Specifies the suffix to append to the name of models that get split for responses and requests based on readOnly and writeOnly schema properties.
packageName
Specify what your 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.
responseFormat
Configure response format for the SDK. Options include envelope, envelope-http, and flat.
enumFormat
Configure the way enums are generated in TypeScript. A value of enum will generate these as TypeScript enums and a value of union will generate as a union of string or number literals.
additionalPackageJSON
Add additional properties into the package.json file. This can be used to add a license, description, or keywords, for example.
templateVersion
This field indicates the version of Speakeasy TypeScript Version to use. It is recommended to use v2 which uses the universal TypeScript generator (opens in a new tab). v1 is used for backward compatibility with the legacy Speakeasy TypeScript generator based on Axios.
methodArguments
Customize how SDK method arguments are arranged and infer optionality. Setting require-security-and-request makes both security and request arguments required. Setting infer-optional-args infers security and request arguments as optional if their fields are optional.
useIndexModules
When set to true (default), the generator will emit index.ts files - also
known as "barrel" file - that re-export all models and custom types in the SDK
and configure package.json#exports where appropriate.
index.ts/index.js files may reduce the number of imports in an application
using an SDK but can come at a cost of slowing down build and test tools and IDE
performance because of the need to crawl all the modules that are re-exported
even if applications need one or two imports from an SDK.
moduleFormat
Customize the JavaScript module format when compiling the SDK. Allowed values include:
commonjs: This is the default setting. It tells the TypeScript compiler to emit CommonJS code (module.exports/require()) and has the broadest compatibility with bundlers, Node.js and newer JavaScript Runtimes. However, it has poor tree-shaking performance with some bundlers such as esbuild or frameworks built on top of esbuild.esm: This setting tells the TypeScript compiler to emit ES Modules (ESM). It has the best tree-shaking performance and is supported by all modern JavaScript runtimes but it cannot be easily used in older Node.js codebases that are still on CommonJS. These older codebases will have to use the asyncimport()function to import the SDK.dual: This setting results in building SDKs out to CommonJS and ESM and configures thepackage.json#exportsfield to help resolveimportandrequireappropriately. Applications using bundlers, modern runtimes or ESM will pull in the ESM build while CommonJS codebases will pull in the CommonJS build. This brings the benefits of ESM, such as reliable tree-shaking performance, while maintaining backwards compatibility.
Tree-shaking is especially useful if SDKs are intended to be used in browsers or serverless environments where bundle size and parsing times matter.
version
The version of an SDK is automatically bumped by Speakeasy. If you specify a version, Speakeasy will use that version on the next generation instead of automatically bumping it.
additionalDependencies
Specifies additional dependencies to be included in the generated package.json dependencies section.
Supports setting dependencies, devDependencies, and peerDependencies.
Each section is a simple object that maps an npm package name to a version range. See the npm docs (opens in a new tab) for more details.
clientServerStatusCodesAsErrors
Set to false to treat error code responses as a standard response object. This overrides the default behavior of the SDK treating 4XX or 5XX responses as returning error objects.
flattenGlobalSecurity
Enable the security object to be passed inline during the SDK instantiation. Recommend setting to true.
imports
The imports field in the SDK generation configuration enables customization of model import paths within the SDK. This allows for tailored organization of models in directories, enhancing how they are imported and referenced by users, and providing flexibility in managing SDK structure.
inputModelSuffix
Specifies the suffix to append to the name of models that get split for requests and responses based on readOnly and writeOnly schema properties.
maxMethodParams
Set a threshold on the number of parameters that can be passed inline to an SDK method. Methods that require more parameters to be passed in will require a request parameters object to be passed in. When maxMethodParams is set to 0, all SDK methods require a request parameters object for passing arguments, eliminating inline parameter passing.
This can be overridden by using the x-speakeasy-max-method-params extension in the OpenAPI spec, see here for full details.
outputModelSuffix
Specifies the suffix to append to the name of models that get split for responses and requests based on readOnly and writeOnly schema properties.
packageName
Specify what your 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.
responseFormat
Configure response format for the SDK. Options include envelope, envelope-http, and flat.
enumFormat
Configure the way enums are generated in TypeScript. A value of enum will generate these as TypeScript enums and a value of union will generate as a union of string or number literals.
additionalPackageJSON
Add additional properties into the package.json file. This can be used to add a license, description, or keywords, for example.
templateVersion
This field indicates the version of Speakeasy TypeScript Version to use. It is recommended to use v2 which uses the universal TypeScript generator (opens in a new tab). v1 is used for backward compatibility with the legacy Speakeasy TypeScript generator based on Axios.
methodArguments
Customize how SDK method arguments are arranged and infer optionality. Setting require-security-and-request makes both security and request arguments required. Setting infer-optional-args infers security and request arguments as optional if their fields are optional.
useIndexModules
When set to true (default), the generator will emit index.ts files - also
known as "barrel" file - that re-export all models and custom types in the SDK
and configure package.json#exports where appropriate.
index.ts/index.js files may reduce the number of imports in an application
using an SDK but can come at a cost of slowing down build and test tools and IDE
performance because of the need to crawl all the modules that are re-exported
even if applications need one or two imports from an SDK.
moduleFormat
Customize the JavaScript module format when compiling the SDK. Allowed values include:
commonjs: This is the default setting. It tells the TypeScript compiler to emit CommonJS code (module.exports/require()) and has the broadest compatibility with bundlers, Node.js and newer JavaScript Runtimes. However, it has poor tree-shaking performance with some bundlers such as esbuild or frameworks built on top of esbuild.esm: This setting tells the TypeScript compiler to emit ES Modules (ESM). It has the best tree-shaking performance and is supported by all modern JavaScript runtimes but it cannot be easily used in older Node.js codebases that are still on CommonJS. These older codebases will have to use the asyncimport()function to import the SDK.dual: This setting results in building SDKs out to CommonJS and ESM and configures thepackage.json#exportsfield to help resolveimportandrequireappropriately. Applications using bundlers, modern runtimes or ESM will pull in the ESM build while CommonJS codebases will pull in the CommonJS build. This brings the benefits of ESM, such as reliable tree-shaking performance, while maintaining backwards compatibility.
Tree-shaking is especially useful if SDKs are intended to be used in browsers or serverless environments where bundle size and parsing times matter.