The gen.yaml File Reference

TIP

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

For manual editing of the gen.yaml file, 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 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

The currently supported version of the Speakeasy gen.yaml configuration file is 2.0.0. Older versions will be automatically upgraded when encountered.

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.

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

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.

optionalPropertyRendering: Options include always, never, and withExample, which renders optional properties only when an example is present in the OpenAPI spec.

Enables or disables the use of development containers and specifies the schema path.

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

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.

OAuth2ClientCredentialsEnabled: Enables the generation of code for handling OAuth 2.0 client credentials for authentication, where possible. Enterprise license only

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.

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

gen.yaml

configVersion: 2.0.0
generation:
  sdkClassName: speakeasybar
  maintainOpenAPIOrder: true
  usageSnippets:
    optionalPropertyRendering: withExample
  devContainers:
    enabled: true
    schemaPath: "path/to/schema"
  useClassNamesForArrayFields: true
  fixes:
    nameResolutionDec2023: true
    parameterOrderingFeb2024: true
    requestResponseComponentNamesFeb2024: true
  auth:
    OAuth2ClientCredentialsEnabled: true
  baseServerUrl: "speakeasy.bar/public/api/"
  mockServer:
    disabled: true
# Add language-specific configs here