# OpenAPI generators.yml reference

> Reference for configuring OpenAPI specifications in your generators.yml file

The `generators.yml` file serves two roles: it declares your OpenAPI specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section).

APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref).

```yaml title="generators.yml"
api:
  specs:
    - openapi: "./openapi.yml"
      origin: "https://api.example.com/openapi.json"
      overlays: "./openapi-overlays.yml"
      overrides: "./openapi-overrides.yml"
      namespace: "v1"
      settings:
        title-as-schema-name: true
        inline-path-parameters: false
        inline-all-of-schemas: true
        prefer-undiscriminated-unions-with-literals: true
        filter:
          endpoints: ["POST /users", "GET /users/{id}"]
        example-generation:
          request:
            max-depth: 2
```

<ParamField path="openapi" type="string" required={true} toc={true}>
  Path to the OpenAPI specification file.
</ParamField>

<ParamField path="origin" type="string" toc={true}>
  URL of the API definition origin for pulling updates. For instructions on how to set up automatic syncing, refer to [Sync your OpenAPI specification](/learn/api-definitions/openapi/sync-your-open-api-specification).
</ParamField>

<ParamField path="overlays" type="string" toc={true}>
  Path to an [OpenAPI Overlay](/learn/api-definitions/openapi/overlays) file. Overlays follow the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) and are the recommended approach for customizing OpenAPI specifications.
</ParamField>

<ParamField path="overrides" type="string" toc={true}>
  Path to OpenAPI overrides file. Consider using `overlays` instead for a standards-based approach.
</ParamField>

<ParamField path="namespace" type="string" toc={true}>
  Namespace for the specification. Useful for configuring a [single package with multiple API versions](/api-definitions/overview/project-structure#option-2-namespace-based-versioning).
</ParamField>

<ParamField path="settings" type="object" toc={true}>
  OpenAPI-specific generation settings for this individual spec. To apply the same settings across all OpenAPI specs, use global [`api.settings`](/learn/sdks/reference/generators-yml#settings) instead.
</ParamField>

<ParamField path="settings.title-as-schema-name" type="boolean" default="false" toc={true}>
  Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.
</ParamField>

<ParamField path="settings.inline-path-parameters" type="boolean" default="true" toc={true}>
  Whether to include path parameters within the generated in-lined request.
</ParamField>

<ParamField path="settings.inline-all-of-schemas" type="boolean" default="false" toc={true}>
  Whether to inline `allOf` schemas during code generation. When true, Fern recursively visits `allOf` schema definitions and inlines them into the child schema. When false, `allOf` schemas are extended through inheritance.

  Enabling this setting allows child schemas to override parent property requirements. For example, a child schema can mark a parent's required property as optional. Without this setting, Fern ignores the child schema's optional declaration and preserves the parent schema's requirement instead.
</ParamField>

<ParamField path="settings.prefer-undiscriminated-unions-with-literals" type="boolean" default="false" toc={true}>
  Whether to prefer undiscriminated unions with literals.
</ParamField>

<ParamField path="settings.only-include-referenced-schemas" type="boolean" default="false" toc={true}>
  Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).
</ParamField>

<ParamField path="settings.respect-nullable-schemas" type="boolean" default="true" toc={true}>
  Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
</ParamField>

<ParamField path="settings.object-query-parameters" type="boolean" default="true" toc={true}>
  Enables parsing deep object query parameters.
</ParamField>

<ParamField path="settings.wrap-references-to-nullable-in-optional" type="boolean" default="false" toc={true}>
  Controls whether references to nullable schemas are wrapped in optional types. When false, nullable references are treated as required fields that can be null.
</ParamField>

<ParamField path="settings.coerce-optional-schemas-to-nullable" type="boolean" default="false" toc={true}>
  Controls whether optional schemas are coerced to nullable types during code generation. When false, optional and nullable are treated as distinct concepts.
</ParamField>

<ParamField path="settings.respect-readonly-schemas" type="boolean" toc={true}>
  Enables exploring readonly schemas in OpenAPI specifications.
</ParamField>

<ParamField path="settings.respect-forward-compatible-enums" type="boolean" default="false" toc={true}>
  Enables respecting forward compatible enums in OpenAPI specifications.
</ParamField>

<ParamField path="settings.use-bytes-for-binary-response" type="boolean" toc={true}>
  Enables using the `bytes` type for binary responses. Defaults to file stream.
</ParamField>

<ParamField path="settings.default-form-parameter-encoding" type="string" default="json" toc={true}>
  The default encoding of form parameters. Options: `form`, `json`.
</ParamField>

<ParamField path="settings.additional-properties-defaults-to" type="boolean" default="false" toc={true}>
  Configure what `additionalProperties` should default to when not explicitly defined on a schema.
</ParamField>

<ParamField path="settings.type-dates-as-strings" type="boolean" default="false" toc={true}>
  If true, convert strings with format date to strings. If false, convert to dates.
</ParamField>

<ParamField path="settings.preserve-single-schema-oneof" type="boolean" default="false" toc={true}>
  If true, preserve oneOf structures with a single schema. If false, unwrap them.
</ParamField>

<ParamField path="settings.filter.endpoints" type="list of strings" toc={true}>
  Endpoints to include in the generated SDK (e.g., "POST /users").
</ParamField>

<ParamField path="settings.example-generation.request.max-depth" type="integer" toc={true}>
  Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.
</ParamField>

<ParamField path="settings.example-generation.response.max-depth" type="integer" toc={true}>
  Controls the maximum depth for which optional properties will have examples generated in responses.
</ParamField>

<ParamField path="settings.coerce-enums-to-literals" type="boolean" default="false" toc={true}>
  Controls whether enums are converted to literal types during code generation. When `false` (default), enums are preserved as enum types, maintaining the original enum structure from your OpenAPI specification. When `true`, enums are coerced to literal types, which can be useful for simpler type representations in generated code.
</ParamField>

<ParamField path="settings.idiomatic-request-names" type="boolean" default="true" toc={true}>
  Controls the naming convention for autogenerated request names. When enabled, places the verb before the noun in request names (e.g., `UsersListRequest` becomes `ListUsersRequest`), following more idiomatic naming patterns.
</ParamField>

<ParamField path="settings.resolve-aliases" type="boolean" default="false" toc={true}>
  Inlines type aliases to simplify your generated SDK. When enabled, reduces
  unnecessary type definitions by replacing simple aliases with their underlying
  types directly. Useful for OpenAPI specs with many primitive or simple type
  aliases.

  Set to `true` to inline all aliases, or use an object with an `except` array
  to preserve specific type aliases:

  ```yaml
  settings:
    # Inline all aliases
    resolve-aliases: true

    # Or preserve specific aliases
    resolve-aliases:
      except:
        - UserId
        - OrganizationId
  ```
</ParamField>

<ParamField path="settings.group-environments-by-host" type="boolean" default="false" toc={true}>
  When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions.
</ParamField>