The gen.yaml file reference

Tip

For most use cases, the speakeasy configure command is the recommended means of interacting with the Speakeasy gen.yaml file. The speakeasy configure command has subcommands for configuring sources, targets, GitHub workflow setups, and package publications. All new targets created using speakeasy quickstart automatically generate workflow files in the .speakeasy/ folder in the root of the target directory.

The gen.yaml file has several sections:

The generation section is essential for SDK configuration
The management and features sections are maintained by Speakeasy and should not be edited
The final section is for language-specific configuration (for more information, see the language-specific configuration docs)

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.

configVersion: 2.0.0

generation

The generation section of the gen.yaml file 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. For more information about SDK generation and targets, see our core concepts documentation.

generation:
  sdkClassName: speakeasybar
  maintainOpenAPIOrder: true
  usageSnippets:
    optionalPropertyRendering: withExample
  devContainers:
    enabled: true
    schemaPath: "path/to/schema"
  useClassNamesForArrayFields: true
  fixes:
    nameResolutionDec2023: true
    parameterOrderingFeb2024: true
    requestResponseComponentNamesFeb2024: true
    securityFeb2025: true
    nameOverrideFeb2026: true
  auth:
    OAuth2ClientCredentialsEnabled: true
  inferSSEOverload: true
  repoUrl: https://github.com/my-org/my-sdk
  repoSubDirectory: go

sdkClassName

Defines the class name of the main imported class in the generated SDK.

  sdkClassName: speakeasybar

maintainOpenAPIOrder

Determines whether the parameters, properties, operations, etc., are maintained in the same order they appear in the OpenAPI document. If set to false, these elements are sorted alphabetically.

  maintainOpenAPIOrder: true

usageSnippets

The options for optionalPropertyRendering include always, never, and withExample, which renders optional properties only when an example is present in the OpenAPI document.

  usageSnippets:
    optionalPropertyRendering: withExample

devContainers

Enables or disables the use of development containers, and specifies the schema path. For more information about development containers and SDK sandboxes, see our SDK sandbox documentation.

  devContainers:
    enabled: true
    schemaPath: "path/to/schema"

useClassNamesForArrayFields

When set to true, array fields use class names instead of child schema types.

  useClassNamesForArrayFields: true

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.
securityFeb2025: Disabling not recommended. Enables changes introduced in February 2025 to the security handling at both the global and operation level, particularly needed to enable per-operation OAuth2 flows. Defaults to true for new SDKs. For older SDKs, setting true is recommended, but will be a breaking change.
nameOverrideFeb2026: Disabling not recommended. Prevents x-speakeasy-name-override values from propagating through $ref resolution or allOf composition. Defaults to true for new SDKs. For older SDKs, setting true is recommended, but can be a breaking change depending on x-speakeasy-name-override usage.

  fixes:
    nameResolutionDec2023: true
    parameterOrderingFeb2024: true
    requestResponseComponentNamesFeb2024: true
    securityFeb2025: true
    nameOverrideFeb2026: true

auth

OAuth2ClientCredentialsEnabled: Enables the generation of code for handling OAuth 2.0 client credentials for authentication, where possible. Business and Enterprise plans only.
hoistGlobalSecurity: When true (default), Speakeasy identifies the most commonly used operation-level security scheme and hoists it to global security if no global security is defined. Set to false to disable this behavior.

For detailed information about authentication configuration, see our guide to customizing security and authentication.

  auth:
    OAuth2ClientCredentialsEnabled: true
    hoistGlobalSecurity: true

Disable security hoisting

Set hoistGlobalSecurity to false to opt out:

auth:
  hoistGlobalSecurity: false

inferSSEOverload

Enables the generation of method overloads for Python SDKs to provide better type safety for Server-Sent Events (SSE) operations. When set to true (default), Speakeasy will automatically create overloaded methods for operations that meet specific criteria:

The operation has a request body
The request body contains a stream field (boolean type)
The operation has exactly two responses: one text/event-stream and one application/json

This feature is currently Python-specific, with support for other languages planned for future releases.

  inferSSEOverload: true

repoUrl

Sets the repository URL for the generated SDK. This value is used in generated package metadata (for example, the repository field in package.json for TypeScript). Setting repoUrl in gen.yaml removes the need to pass the -r CLI flag during generation.

If both the CLI flag (-r) and the gen.yaml value are provided, the CLI flag takes precedence. If neither is set, the value from gen.lock (saved from a previous generation) is used.

  repoUrl: https://github.com/my-org/my-sdk

repoSubDirectory

Sets the subdirectory within the repository where the SDK is located. This is useful for monorepo setups where multiple SDKs live in the same repository. Setting repoSubDirectory in gen.yaml removes the need to pass the -b CLI flag during generation.

Like repoUrl, the CLI flag (-b) takes precedence over the gen.yaml value.

  repoSubDirectory: go

baseServerUrl

Used to declare the base server URL. It overrides the servers field in the OpenAPI document if present, or provides a server URL if the servers field is absent.

  baseServerUrl: "speakeasy.bar/public/api/"

requestBodyFieldName

Changes the field name of the request body parameter from using a flattened request object name to using a generic name. When set to body, the request body parameter will be named body instead of using the flattened request object name. This provides a more consistent and predictable parameter naming convention across your SDK methods.

  requestBodyFieldName: body

tests

Configuration for SDK test generation. For more information about SDK testing, see the SDK contract testing documentation.

generateTests: Controls whether tests are generated during speakeasy run. Defaults to false.
generateNewTests: Controls whether new tests are automatically added for newly discovered operations. Defaults to false.
skipResponseBodyAssertions: When true, generated tests omit all response body assertions while still asserting on status codes. Useful when API response bodies are non-deterministic (e.g., dynamic data, timestamps, random IDs) or when using a test server or mock that doesn’t return realistic response payloads. Defaults to false. Applies globally to all generated tests for the target with no per-operation override.

  tests:
    generateTests: true
    generateNewTests: true
    skipResponseBodyAssertions: false

mockServer

Disables the generation and use of a mock HTTP server with generated tests.

  mockServer:
    disabled: true

schemas

Configuration for how OpenAPI schemas are processed during SDK generation.

allOfMergeStrategy

Controls how allOf constructs in OpenAPI schemas are merged. For detailed information about merge strategies, see the allOf schemas documentation.

deepMerge (default for new SDKs): Recursively merges nested properties within objects, preserving properties from all schemas in the allOf array.
shallowMerge (legacy behavior): Replaces entire property blocks when merging, which can result in lost properties from earlier schemas.

  schemas:
    allOfMergeStrategy: deepMerge

multipartArrayFormat

Controls how arrays are serialized in multipart/form-data requests. This option determines whether array field names include brackets ([]) or use the RFC 7578-compliant approach of repeating the same field name.

legacy (default for existing SDKs): Appends [] to array field names (e.g., files[]). This maintains backward compatibility with existing SDKs but is non-compliant with RFC 7578.
standard (default for new SDKs): Uses the RFC 7578-compliant format by repeating the same field name for each array element (e.g., multiple files fields). This is the correct multipart/form-data encoding according to RFC 7578 Section 4.3.

  multipartArrayFormat: standard

Migration note: Changing from legacy to standard is a breaking change. APIs expecting field names with [] suffixes will need to be updated to handle the RFC-compliant format.

versioningStrategy

Controls how SDK versions are determined during generation. For more information about SDK versioning, see our SDK versioning documentation.

automatic (default): Automatically bumps the SDK version based on changes to the OpenAPI spec, configuration, or generator version.
manual: Uses the version specified in gen.yaml as-is without automatic bumping. Use this when you want full control over SDK versioning.

  versioningStrategy: manual

When set to manual, the SDK version will only change when you explicitly update the version field in your language-specific configuration or use speakeasy bump commands.