Skip to content

Add generators.yml reference page to OpenAPI section; document inline-all-of-schemas (API Definitions) #578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 26, 2025
Merged

Add generators.yml reference page to OpenAPI section; document inline-all-of-schemas (API Definitions) #578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions fern/products/api-def/api-def.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ navigation:
- page: FastAPI
path: ./openapi-pages/server-frameworks/fastapi.mdx
slug: fastapi
- page: generators.yml reference
path: ./openapi-pages/reference/generators-reference.mdx
- section: AsyncAPI
collapsed: true
slug: asyncapi
Expand Down
8 changes: 8 additions & 0 deletions fern/products/api-def/openapi-pages/reference/generators-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: OpenAPI generators.yml reference
description: Reference for configuring OpenAPI specifications in your generators.yml file
---

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

<Markdown src="/snippets/openapi-specs.mdx" />
104 changes: 2 additions & 102 deletions fern/products/sdks/reference/generators-yml-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,109 +171,9 @@ api:

### Specification Types

#### OpenAPI
#### OpenAPI

```yaml
api:
specs:
- openapi: "./openapi.yml"
origin: "https://api.example.com/openapi.json"
overrides: "./openapi-overrides.yml"
namespace: "v1"
settings:
title-as-schema-name: true
inline-path-parameters: false
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 polling updates.
</ParamField>

<ParamField path="overrides" type="string" toc={true}>
Path to OpenAPI overrides file.
</ParamField>

<ParamField path="namespace" type="string" toc={true}>
Namespace for the specification.
</ParamField>

<ParamField path="settings" type="OpenAPISettingsSchema" toc={true}>
OpenAPI-specific generation settings.
</ParamField>

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

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

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

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

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

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

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

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

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

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

<ParamField path="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="filter.endpoints" type="list<string>" toc={true}>
Endpoints to include in the generated SDK (e.g., "POST /users").
</ParamField>

<ParamField path="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="example-generation.response.max-depth" type="integer" toc={true}>
Controls the maximum depth for which optional properties will have examples generated in responses.
</ParamField>
<Markdown src="/snippets/openapi-specs.mdx" />

#### AsyncAPI

Expand Down
108 changes: 108 additions & 0 deletions fern/snippets/openapi-specs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
```yaml title="generators.yml"
api:
specs:
- openapi: "./openapi.yml"
origin: "https://api.example.com/openapi.json"
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 polling updates.
</ParamField>

<ParamField path="overrides" type="string" toc={true}>
Path to OpenAPI overrides file.
</ParamField>

<ParamField path="namespace" type="string" toc={true}>
Namespace for the specification.
</ParamField>

<ParamField path="settings" type="OpenAPISettingsSchema" toc={true}>
OpenAPI-specific generation settings.
</ParamField>

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

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

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

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

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

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

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

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

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

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

<ParamField path="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="filter.endpoints" type="list<string>" toc={true}>
Endpoints to include in the generated SDK (e.g., "POST /users").
</ParamField>

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