> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# 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).

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: "./openapi.yml"
      origin: "https://api.example.com/openapi.json"
      overlays: "./openapi-overlays.yml"
      overrides: "./openapi-overrides.yml" # or a list of paths
      namespace: "v1"
      settings:
        title-as-schema-name: true
        ignore-tags: true
        inline-path-parameters: false
        inline-all-of-schemas: true
        prefer-undiscriminated-unions-with-literals: true
        respect-parameter-content: true
        filter:
          endpoints: ["POST /users", "GET /users/{id}"]
        example-generation:
          request:
            max-depth: 2
    - openapi:
        git:
          repo: https://github.com/org/private-api-specs.git
          ref: main
          path: openapi/service-a.yml
      overrides: ./local-overrides.yml
```

**`openapi`** `string | git` — required

Location of the OpenAPI specification file. Accepts a local file path or a remote git reference.

```yaml
# Local file
openapi: ./openapi.yml

# Remote git repository
openapi:
  git:
    repo: https://github.com/org/api-specs.git
    ref: main
    path: openapi/service.yml
```

---

**`openapi.git.repo`** `string` — required

The git repository URL (e.g., `https://github.com/org/repo.git`). The CLI shallow-clones this repository at generation time using your system's git credential configuration (credential helpers, SSH keys, `GIT_ASKPASS`).

---

**`openapi.git.ref`** `string`

Branch, tag, or commit SHA to check out. Defaults to the repository's default branch when omitted.

---

**`openapi.git.path`** `string` — required

Path to the spec file within the repository.

---

**`origin`** `string`

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).

---

**`overlays`** `string`

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.

---

**`overrides`** `string | list of strings`

Path to an OpenAPI [overrides](/learn/api-definitions/openapi/overrides) file, or a list of paths to multiple override files applied sequentially. Consider using `overlays` instead for a standards-based approach.

```yaml
# Single override file
overrides: ./overrides.yml

# Multiple override files (applied in order)
overrides:
  - ./base-overrides.yml
  - ./sdk-overrides.yml
```

---

**`namespace`** `string`

Namespace for the specification. Useful for configuring a [single package with multiple API versions](/learn/api-definitions/overview/project-structure#option-2-namespace-based-versioning).

---

**`settings`** `object`

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.

---

**`settings.title-as-schema-name`** `boolean` — default: false

Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.

---

**`settings.inline-path-parameters`** `boolean` — default: true

Whether to include path parameters within the generated in-lined request.

---

**`settings.inline-all-of-schemas`** `boolean` — default: false

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.

---

**`settings.prefer-undiscriminated-unions-with-literals`** `boolean` — default: false

Whether to prefer undiscriminated unions with literals.

---

**`settings.only-include-referenced-schemas`** `boolean` — default: false

Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).

---

**`settings.respect-nullable-schemas`** `boolean` — default: true

Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.

---

**`settings.object-query-parameters`** `boolean` — default: true

Enables parsing deep object query parameters.

---

**`settings.wrap-references-to-nullable-in-optional`** `boolean` — default: false

Controls whether references to nullable schemas are wrapped in optional types. When false, nullable references are treated as required fields that can be null.

---

**`settings.coerce-optional-schemas-to-nullable`** `boolean` — default: false

Controls whether optional schemas are coerced to nullable types during code generation. When false, optional and nullable are treated as distinct concepts.

---

**`settings.any-of-sibling-properties-as-object`** `boolean` — default: false

Converts a schema whose `anyOf` branches only mark sibling `properties` as `required` (an "at least one of" constraint) into a single object with optional fields instead of an undiscriminated union, so a request body that sets several of those properties keeps all of them instead of dropping all but one. Off by default because it changes generated types. Since every property is generated as optional, the SDK doesn't enforce that at least one is set; the API rejects a request that omits all of them.

---

**`settings.respect-readonly-schemas`** `boolean`

Enables exploring readonly schemas in OpenAPI specifications.

---

**`settings.respect-parameter-content`** `boolean` — default: false

Types a header parameter declared with a JSON `content` map from that schema instead of falling back to `string`, so SDKs get a typed object and the API Reference renders per-field inputs. Off by default because it changes generated SDK method signatures. Query parameters declared with `content` stay `string`.

---

**`settings.respect-forward-compatible-enums`** `boolean` — default: false

Enables respecting forward compatible enums in OpenAPI specifications.

---

**`settings.use-bytes-for-binary-response`** `boolean`

Enables using the `bytes` type for binary responses. Defaults to file stream.

---

**`settings.default-form-parameter-encoding`** `string` — default: json

The default encoding of form parameters. Options: `form`, `json`.

---

**`settings.additional-properties-defaults-to`** `boolean` — default: false

Configure what `additionalProperties` should default to when not explicitly defined on a schema.

---

**`settings.type-dates-as-strings`** `boolean` — default: false

If true, convert strings with format date to strings. If false, convert to dates.

---

**`settings.preserve-single-schema-oneof`** `boolean` — default: false

If true, preserve oneOf structures with a single schema. If false, unwrap them. For a `oneOf` nested inside an `allOf`, use [`preserve-one-of-in-all-of`](/learn/api-definitions/openapi/generators-yml-reference#settingspreserve-one-of-in-all-of).

---

**`settings.preserve-one-of-in-all-of`** `boolean` — default: false

Whether to keep a `oneOf` or `anyOf` that appears as a member of an `allOf` as a union. When `false`, every variant's properties are merged into a single object and marked optional, which makes invalid property combinations representable. When `true`, the `allOf` is distributed over the union: `allOf: [oneOf: [A, B, C], S]` becomes `oneOf: [A & S, B & S, C & S]`, an undiscriminated union in which each variant keeps its own required properties alongside the shared ones.

Enabling this setting changes the generated request and response shapes for affected schemas in every SDK, and the API Reference renders a variant selector for them. Union members that declare a [`discriminator`](/learn/api-definitions/openapi/extensions/discriminator-context) are left intact.

---

**`settings.filter`** `object`

Filter to apply to the OpenAPI specification. Use this to limit which endpoints are included in the generated SDK or API Reference docs [based on their paths](/learn/api-definitions/openapi/extensions/audiences#path-based-filtering).

For tag-based filtering instead of path-based filtering, use [`audiences`](/learn/sdks/reference/generators-yml#audiences) at the `group` level.

---

**`settings.filter.endpoints`** `list of strings`

Endpoints to include in the generated SDK. Specify endpoints in the format `METHOD /path` (e.g., `POST /users`, `GET /users/{id}`). Only the listed endpoints will be included in the generated SDK; all other endpoints will be excluded. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `payments::POST /users`).

---

**`settings.example-generation.request.max-depth`** `integer`

Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.

---

**`settings.example-generation.response.max-depth`** `integer`

Controls the maximum depth for which optional properties will have examples generated in responses.

---

**`settings.coerce-enums-to-literals`** `boolean` — default: false

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.

---

**`settings.idiomatic-request-names`** `boolean` — default: 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.

---

**`settings.ignore-tags`** `boolean` — default: false

Ignores operation-level OpenAPI `tags` when determining SDK structure. Endpoints fall back to the root package (or their `namespace`), and method names are derived from each operation's `operationId`. See [ignore tags](/learn/api-definitions/openapi/extensions/method-names#ignore-tags) for precedence rules and examples.

---

**`settings.resolve-aliases`** `boolean` — default: false

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
```

---

**`settings.respect-per-spec-base-path`** `boolean` — default: false

When merging multiple OpenAPI specs, applies each document's [`x-fern-base-path`](/learn/api-definitions/openapi/extensions/base-path) to its own endpoints only. When `false`, one document's base path is prepended to every endpoint across all specs. Parameterized base paths such as `/{tenant}/v1` stay at the API root, and differing parameterized base paths across documents raise a conflict.

If you worked around the dropped prefix by adding it to your [server URL](/learn/api-definitions/openapi/extensions/server-names) (for example, `https://api.example.com/api/v3`), remove it when enabling this setting. Otherwise the prefix is applied twice.

---

**`settings.group-environments-by-host`** `boolean` — default: false

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.

---

**`settings.namespaced-errors`** `boolean` — default: false

When enabled, shared error responses tagged with [`x-fern-sdk-namespace`](/learn/api-definitions/openapi/extensions/sdk-namespaces) in `components.responses` are generated as typed errors in that namespace (for example, `plants.TooManyRequestsError`) instead of being compared API-wide by status code. Applies only to the spec that sets it.

```yaml
settings:
  namespaced-errors: true
```

---

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