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
generation
section is important for SDK configuration. - The
management
andfeatures
sections 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.
mockServer
Disables the generation and usage of a mock HTTP server with generated tests.
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.
auth
OAuth2ClientCredentialsEnabled
: Enables the generation of code for handling OAuth 2.0 client credentials for authentication, where possible. Enterprise license only
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. 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#exports
field to help resolveimport
andrequire
appropriately. 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.
envVarPrefix
Setting an env var prefix config value allows your users to set global parameters and security options via environment variables:
- It will now be possible to provide global parameters via env variable at
{PREFIX}_{GLOBALNAME}
. Documentation for this will be automatically added to your README sections. - Security options can also be set via env variables when they are not provided as an input to the SDK object. For a single security field
api_key
, that can now be set by an env variable{PREFIX}_{API_KEY}
. Note: In some cases adding anenvVarPrefix
may slightly change the structure of your security options. If you have required global security, that will now become optional global security so it can be set via an environment variable as well.
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. 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#exports
field to help resolveimport
andrequire
appropriately. 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.
envVarPrefix
Setting an env var prefix config value allows your users to set global parameters and security options via environment variables:
- It will now be possible to provide global parameters via env variable at
{PREFIX}_{GLOBALNAME}
. Documentation for this will be automatically added to your README sections. - Security options can also be set via env variables when they are not provided as an input to the SDK object. For a single security field
api_key
, that can now be set by an env variable{PREFIX}_{API_KEY}
. Note: In some cases adding anenvVarPrefix
may slightly change the structure of your security options. If you have required global security, that will now become optional global security so it can be set via an environment variable as well.