gen.yaml Reference
TIP
For most use cases we recommend interacting with the Speakeasy (gen.yaml) through the speakeasy configure command.
This command has subcommands to configure your sources, targets, github setup and package publishing. All new targets created through speakeasy quickstart will automatically have a workflow
file created in the .speakeasy/ folder in the root of their target directory.
For editing the gen.yaml file manually, 
Speakeasy's VSCode extension (opens in a new tab) provides syntax highlighting and autocompletion,
in addition to linting for OpenAPI documents, and our 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 example,
typescript. 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 version 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 OAuth2 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 version 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 including in the generated package.json dependencies section.
Supports setting dependencies, devDependencies and peerDependencies.
Each section in a simple object that maps a 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 vs responses based on readOnly & 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 overriden 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 vs requests based on readOnly & 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 backwards compatibility with the legacy Speakeasy Typescript generator based on axios.
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 including in the generated package.json dependencies section.
Supports setting dependencies, devDependencies and peerDependencies.
Each section in a simple object that maps a 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 vs responses based on readOnly & 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 overriden 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 vs requests based on readOnly & 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 backwards compatibility with the legacy Speakeasy Typescript generator based on axios.