OpenAPI

OpenAPI generators.yml reference

Configure how your OpenAPI specification is processed and transformed into SDKs using the generators.yml configuration file.

generators.yml
1api:
2  specs:
3    - openapi: "./openapi.yml"
4      origin: "https://api.example.com/openapi.json"
5      overrides: "./openapi-overrides.yml"
6      namespace: "v1"
7      settings:
8        title-as-schema-name: true
9        inline-path-parameters: false
10        inline-all-of-schemas: true
11        prefer-undiscriminated-unions-with-literals: true
12        filter:
13          endpoints: ["POST /users", "GET /users/{id}"]
14        example-generation:
15          request:
16            max-depth: 2
openapi
stringRequired

Path to the OpenAPI specification file.

origin
string

URL of the API definition origin for polling updates.

overrides
string

Path to OpenAPI overrides file.

namespace
string

Namespace for the specification.

settings
OpenAPISettingsSchema

OpenAPI-specific generation settings.

title-as-schema-name
booleanDefaults to true

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

inline-path-parameters
booleanDefaults to false

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

inline-all-of-schemas
booleanDefaults to 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.

prefer-undiscriminated-unions-with-literals
booleanDefaults to false

Whether to prefer undiscriminated unions with literals.

only-include-referenced-schemas
booleanDefaults to false

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

respect-nullable-schemas
booleanDefaults to false

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

object-query-parameters
boolean

Enables parsing deep object query parameters.

respect-readonly-schemas
boolean

Enables exploring readonly schemas in OpenAPI specifications.

respect-forward-compatible-enums
booleanDefaults to false

Enables respecting forward compatible enums in OpenAPI specifications.

use-bytes-for-binary-response
boolean

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

default-form-parameter-encoding
FormParameterEncodingDefaults to json

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

additional-properties-defaults-to
booleanDefaults to false

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

type-dates-as-strings
booleanDefaults to true

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

preserve-single-schema-oneof
booleanDefaults to false

If true, preserve oneOf structures with a single schema. If false, unwrap them.

filter.endpoints
list<string>

Endpoints to include in the generated SDK (e.g., “POST /users”).

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.

example-generation.response.max-depth
integer

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