> This page is for API Definitions. > 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 respect-operation-id-word-boundaries: 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#combined-sdks-from-multiple-apis). --- **`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. Use [`error-responses`](/learn/sdks/reference/generators-yml#settingserror-responses) to give 4xx/5xx responses a shared typed body during import. --- **`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.respect-operation-id-word-boundaries`** `boolean` — default: false Splits an `operationId` on separators, camelCase transitions, and digits when building API Reference URL slugs, and strips the tag prefix. When `false`, an `operationId` that contains an underscore or digit is split only on separators, so `Plants_ListPlantVarieties` under the `plants` tag becomes `/plants/listplantvarieties` instead of `/plants/list-plant-varieties`. Affects API Reference URLs only; generated SDK method names are unchanged. Enabling this setting moves existing API Reference URLs. Add [redirects](/learn/docs/seo/redirects) for the old paths and update hardcoded links in the same change. --- **`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. > **Warning** > > 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 ``` ---