# The gen.yaml file reference 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. ```yaml 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](/docs/sdks/core-concepts#sdk-generation). ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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](/docs/manage/sdk-sandbox). ```yaml devContainers: enabled: true schemaPath: "path/to/schema" ``` ### useClassNamesForArrayFields When set to true, array fields use class names instead of child schema types. ```yaml 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. ```yaml 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](/docs/customize/authentication/configuration). ```yaml auth: OAuth2ClientCredentialsEnabled: true hoistGlobalSecurity: true ``` #### Disable security hoisting Set `hoistGlobalSecurity` to `false` to opt out: ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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. ```yaml requestBodyFieldName: body ``` ### tests Configuration for SDK test generation. For more information about SDK testing, see the [SDK contract testing documentation](/docs/sdk-testing/bootstrapping-test-generation). - `generateTests`: Controls whether tests are generated during [`speakeasy run`](/docs/speakeasy-reference/cli/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. ```yaml tests: generateTests: true generateNewTests: true skipResponseBodyAssertions: false ``` ### mockServer Disables the generation and use of a mock HTTP server with generated tests. ```yaml 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](/docs/customize/data-model/allof-schemas). - `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. ```yaml 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. ```yaml 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](/docs/sdks/manage/versioning). - `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. ```yaml 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.