From 78a8e2ec57174ed81b049e5610ae04795cccdb57 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 27 Apr 2026 20:22:47 +0000 Subject: [PATCH 1/8] Add x-fern-default extension documentation --- fern/products/api-def/api-def.yml | 2 + .../api-def/openapi/extensions/default.mdx | 78 +++++++++++++++++++ .../api-def/openapi/extensions/overview.md | 1 + 3 files changed, 81 insertions(+) create mode 100644 fern/products/api-def/openapi/extensions/default.mdx diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index 36969fe38..52197fec1 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -49,6 +49,8 @@ navigation: path: ./openapi/extensions/availability.mdx - page: Base path path: ./openapi/extensions/base-path.mdx + - page: Default values + path: ./openapi/extensions/default.mdx - page: Enum descriptions, names, and availability path: ./openapi/extensions/enums.mdx slug: enum-descriptions-and-names diff --git a/fern/products/api-def/openapi/extensions/default.mdx b/fern/products/api-def/openapi/extensions/default.mdx new file mode 100644 index 000000000..c2d8d1ac6 --- /dev/null +++ b/fern/products/api-def/openapi/extensions/default.mdx @@ -0,0 +1,78 @@ +--- +title: Default values +headline: Default values (OpenAPI) +description: Use `x-fern-default` to set client-side default values for path, header, and query parameters in generated SDKs. +--- + + +The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter. When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. + +This is useful for pinning an API version header or a region path parameter while still allowing callers to override the value. + + + `x-fern-default` supports `string` and `boolean` values. Other types (such as numbers) are ignored. + + +## Path parameters + +Use `x-fern-default` on a path parameter to provide a default that the SDK sends automatically. This makes a normally required path parameter optional in the generated SDK. + +```yaml {8} title="openapi.yml" +paths: + /regions/{region}/resources: + get: + operationId: list_resources + parameters: + - name: region + in: path + required: true + x-fern-default: "us-east-1" + schema: + type: string +``` + +## Headers + +Use `x-fern-default` on a header parameter to pin a default value, such as an API version: + +```yaml {8} title="openapi.yml" +paths: + /users: + get: + operationId: list_users + parameters: + - name: X-API-Version + in: header + x-fern-default: "2024-02-08" + schema: + type: string +``` + +## Query parameters + +Use `x-fern-default` on a query parameter to set a default that the SDK sends when the caller omits it: + +```yaml {8} title="openapi.yml" +paths: + /search: + get: + operationId: search + parameters: + - name: sort + in: query + x-fern-default: "relevance" + schema: + type: string +``` + +## Supported languages + +`x-fern-default` is supported in the following SDK generators: + +- TypeScript +- Python +- Java +- Go +- C# +- Ruby +- PHP diff --git a/fern/products/api-def/openapi/extensions/overview.md b/fern/products/api-def/openapi/extensions/overview.md index 0b691fd2e..f1dc736d3 100644 --- a/fern/products/api-def/openapi/extensions/overview.md +++ b/fern/products/api-def/openapi/extensions/overview.md @@ -20,6 +20,7 @@ The table below shows all available extensions and links to detailed documentati | [`x-fern-bearer`](/api-definitions/openapi/authentication#bearer-security-scheme) | Customize bearer authentication parameter names and environment variables | | [`x-fern-availability`](./availability) | Mark availability status (beta, generally-available, deprecated) | | [`x-fern-base-path`](./base-path) | Set base path prepended to all endpoints | +| [`x-fern-default`](./default-values) | Set client-side default values for path, header, and query parameters | | [`x-displayName`](./tag-display-names) | Specify how tag names display in your API Reference | | [`x-fern-enum`](./enum-descriptions-and-names) | Add descriptions, custom names, and deprecation status to enum values | | [`x-fern-examples`](./request-response-examples) | Associate request and response examples | From 7e295c8421843e8af6858d5a373c7096e64d6d93 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 27 Apr 2026 20:29:55 +0000 Subject: [PATCH 2/8] Move supported languages into intro paragraph --- .../products/api-def/openapi/extensions/default.mdx | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/fern/products/api-def/openapi/extensions/default.mdx b/fern/products/api-def/openapi/extensions/default.mdx index c2d8d1ac6..b58f45800 100644 --- a/fern/products/api-def/openapi/extensions/default.mdx +++ b/fern/products/api-def/openapi/extensions/default.mdx @@ -5,7 +5,7 @@ description: Use `x-fern-default` to set client-side default values for path, he --- -The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter. When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. +The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter. When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. This is supported in TypeScript, Python, Java, Go, C#, Ruby, and PHP. This is useful for pinning an API version header or a region path parameter while still allowing callers to override the value. @@ -65,14 +65,3 @@ paths: type: string ``` -## Supported languages - -`x-fern-default` is supported in the following SDK generators: - -- TypeScript -- Python -- Java -- Go -- C# -- Ruby -- PHP From c4e46488be9765a46b4ebd1065bba9dc115cecd7 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 27 Apr 2026 20:31:32 +0000 Subject: [PATCH 3/8] Use boolean example for query parameter default --- fern/products/api-def/openapi/extensions/default.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fern/products/api-def/openapi/extensions/default.mdx b/fern/products/api-def/openapi/extensions/default.mdx index b58f45800..2b1dbc995 100644 --- a/fern/products/api-def/openapi/extensions/default.mdx +++ b/fern/products/api-def/openapi/extensions/default.mdx @@ -58,10 +58,10 @@ paths: get: operationId: search parameters: - - name: sort + - name: verbose in: query - x-fern-default: "relevance" + x-fern-default: false schema: - type: string + type: boolean ``` From 23e32f1a57ef9750484f7e20a1f27d2c0f2126d1 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 27 Apr 2026 16:53:33 -0400 Subject: [PATCH 4/8] refine description --- .../api-def/openapi/extensions/default.mdx | 15 +++++++-------- fern/products/sdks/deep-dives/generated-sdk.mdx | 4 ++++ 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/fern/products/api-def/openapi/extensions/default.mdx b/fern/products/api-def/openapi/extensions/default.mdx index 2b1dbc995..bef230017 100644 --- a/fern/products/api-def/openapi/extensions/default.mdx +++ b/fern/products/api-def/openapi/extensions/default.mdx @@ -4,20 +4,19 @@ headline: Default values (OpenAPI) description: Use `x-fern-default` to set client-side default values for path, header, and query parameters in generated SDKs. --- - -The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter. When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. This is supported in TypeScript, Python, Java, Go, C#, Ruby, and PHP. +The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter. When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. `x-fern-default` supports `string` and `boolean` values; other types (such as numbers) are ignored. This is useful for pinning an API version header or a region path parameter while still allowing callers to override the value. - - `x-fern-default` supports `string` and `boolean` values. Other types (such as numbers) are ignored. + + `x-fern-default` is supported for TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs. ## Path parameters -Use `x-fern-default` on a path parameter to provide a default that the SDK sends automatically. This makes a normally required path parameter optional in the generated SDK. +In the example below, the SDK sends `us-east-1` for `region` when the caller doesn't specify one. -```yaml {8} title="openapi.yml" +```yaml {9} title="openapi.yml" paths: /regions/{region}/resources: get: @@ -33,7 +32,7 @@ paths: ## Headers -Use `x-fern-default` on a header parameter to pin a default value, such as an API version: +In the example below, the SDK sends `2024-02-08` for `X-API-Version` when the caller doesn't specify one. ```yaml {8} title="openapi.yml" paths: @@ -50,7 +49,7 @@ paths: ## Query parameters -Use `x-fern-default` on a query parameter to set a default that the SDK sends when the caller omits it: +In the example below, the SDK sends `false` for `verbose` when the caller doesn't specify one. ```yaml {8} title="openapi.yml" paths: diff --git a/fern/products/sdks/deep-dives/generated-sdk.mdx b/fern/products/sdks/deep-dives/generated-sdk.mdx index 7288fec5c..9bb4f1613 100644 --- a/fern/products/sdks/deep-dives/generated-sdk.mdx +++ b/fern/products/sdks/deep-dives/generated-sdk.mdx @@ -47,6 +47,10 @@ When the API returns a 4xx or 5xx status code, the SDK throws an error that incl When you define webhooks in your API spec, Fern automatically [generates utilities that allow your users to verify webhook signatures](./webhook-signature-verification) and ensure events originate from your API. +## Default parameter values + +Path, header, and query parameters can ship with [default values](/learn/api-definitions/openapi/extensions/default) configured by the API author. The SDK makes those parameters optional and sends the default when the caller doesn't provide one — useful for things like pinned API version headers or default regions. Supported in TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs. + ## Customization options Your SDK users can configure individual requests using language-specific options: From 520fb54d7a5a6f215cec86989072738bb7fbad33 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 27 Apr 2026 16:57:00 -0400 Subject: [PATCH 5/8] wording nit --- fern/products/sdks/deep-dives/generated-sdk.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/deep-dives/generated-sdk.mdx b/fern/products/sdks/deep-dives/generated-sdk.mdx index 9bb4f1613..1a36255f0 100644 --- a/fern/products/sdks/deep-dives/generated-sdk.mdx +++ b/fern/products/sdks/deep-dives/generated-sdk.mdx @@ -49,7 +49,7 @@ When you define webhooks in your API spec, Fern automatically [generates utiliti ## Default parameter values -Path, header, and query parameters can ship with [default values](/learn/api-definitions/openapi/extensions/default) configured by the API author. The SDK makes those parameters optional and sends the default when the caller doesn't provide one — useful for things like pinned API version headers or default regions. Supported in TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs. +You can configure [default values](/learn/api-definitions/openapi/extensions/default) for path, header, and query parameters. The SDK makes those parameters optional and sends the default when the caller doesn't provide one — useful for things like pinning an API version header or default region. Supported in TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs. ## Customization options From f5b8cd04f8e085bf1c7c4456888bcb02192eda20 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 27 Apr 2026 21:09:32 +0000 Subject: [PATCH 6/8] Add x-fern-default support for global headers --- fern/products/api-def/openapi/extensions/default.mdx | 11 +++++++++++ .../api-def/openapi/extensions/global-headers.mdx | 9 +++++++++ 2 files changed, 20 insertions(+) diff --git a/fern/products/api-def/openapi/extensions/default.mdx b/fern/products/api-def/openapi/extensions/default.mdx index 2b1dbc995..66bb57762 100644 --- a/fern/products/api-def/openapi/extensions/default.mdx +++ b/fern/products/api-def/openapi/extensions/default.mdx @@ -48,6 +48,17 @@ paths: type: string ``` +## Global headers + +`x-fern-default` also works inside [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers) entries. This is useful for pinning a version header across all endpoints while still allowing callers to override it: + +```yaml {4} title="openapi.yml" +x-fern-global-headers: + - header: X-API-Version + name: version + x-fern-default: "2024-02-08" +``` + ## Query parameters Use `x-fern-default` on a query parameter to set a default that the SDK sends when the caller omits it: diff --git a/fern/products/api-def/openapi/extensions/global-headers.mdx b/fern/products/api-def/openapi/extensions/global-headers.mdx index af52eb191..32ca607f8 100644 --- a/fern/products/api-def/openapi/extensions/global-headers.mdx +++ b/fern/products/api-def/openapi/extensions/global-headers.mdx @@ -30,6 +30,15 @@ x-fern-global-headers: When you define global headers using `x-fern-global-headers`, you must [include them in your `x-fern-examples`](/api-definitions/openapi/extensions/request-response-examples). +You can also set a client-side default value on a global header using [`x-fern-default`](/learn/api-definitions/openapi/extensions/default-values). The generated SDK makes the header optional and sends the default when the caller omits it: + +```yaml {4} title="openapi.yml" +x-fern-global-headers: + - header: X-API-Version + name: version + x-fern-default: "2024-02-08" +``` + Alternatively, you can add headers to the [`api` block in your `generators.yml` file](/learn/sdks/reference/generators-yml#headers): ```yaml title="generators.yml" From 91fd2df4746e99ed602fd43b735aca5bf53fff87 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 27 Apr 2026 17:47:01 -0400 Subject: [PATCH 7/8] refine organization --- .../api-def/openapi/extensions/default.mdx | 24 +++++++++---------- .../openapi/extensions/global-headers.mdx | 13 +++++++--- .../deep-dives/configure-global-headers.mdx | 2 ++ .../sdks/deep-dives/generated-sdk.mdx | 2 +- 4 files changed, 25 insertions(+), 16 deletions(-) diff --git a/fern/products/api-def/openapi/extensions/default.mdx b/fern/products/api-def/openapi/extensions/default.mdx index fdf551a23..c68b1b019 100644 --- a/fern/products/api-def/openapi/extensions/default.mdx +++ b/fern/products/api-def/openapi/extensions/default.mdx @@ -4,7 +4,7 @@ headline: Default values (OpenAPI) description: Use `x-fern-default` to set client-side default values for path, header, and query parameters in generated SDKs. --- -The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter. When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. `x-fern-default` supports `string` and `boolean` values; other types (such as numbers) are ignored. +The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter, including headers defined under [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers). When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. `x-fern-default` supports `string` and `boolean` values; other types (such as numbers) are ignored. This is useful for pinning an API version header or a region path parameter while still allowing callers to override the value. @@ -47,17 +47,6 @@ paths: type: string ``` -## Global headers - -`x-fern-default` also works inside [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers) entries. This is useful for pinning a version header across all endpoints while still allowing callers to override it: - -```yaml {4} title="openapi.yml" -x-fern-global-headers: - - header: X-API-Version - name: version - x-fern-default: "2024-02-08" -``` - ## Query parameters In the example below, the SDK sends `false` for `verbose` when the caller doesn't specify one. @@ -75,3 +64,14 @@ paths: type: boolean ``` +## Global headers + +In the example below, the SDK sends `2024-02-08` for the `X-API-Version` global header when the caller doesn't specify one. + +```yaml {4} title="openapi.yml" +x-fern-global-headers: + - header: X-API-Version + name: version + x-fern-default: "2024-02-08" +``` + diff --git a/fern/products/api-def/openapi/extensions/global-headers.mdx b/fern/products/api-def/openapi/extensions/global-headers.mdx index 32ca607f8..898b669e7 100644 --- a/fern/products/api-def/openapi/extensions/global-headers.mdx +++ b/fern/products/api-def/openapi/extensions/global-headers.mdx @@ -15,9 +15,11 @@ class Client: def __init__(self, *, apiKey: str): ``` -To configure global headers, Fern will automatically pull out headers that are used in every request, or the majority of requests, and mark them as global. +Fern automatically pulls out headers that are used in every request, or the majority of requests, and marks them as global. -In order to label additional headers as global, or to alias the names of global headers, you can leverage the `x-fern-global-headers` extension: +## In your OpenAPI spec + +To label additional headers as global, or to alias the names of global headers, use the `x-fern-global-headers` extension: ```yaml title="openapi.yml" x-fern-global-headers: @@ -26,11 +28,14 @@ x-fern-global-headers: - header: userpool_id optional: true ``` + When you define global headers using `x-fern-global-headers`, you must [include them in your `x-fern-examples`](/api-definitions/openapi/extensions/request-response-examples). -You can also set a client-side default value on a global header using [`x-fern-default`](/learn/api-definitions/openapi/extensions/default-values). The generated SDK makes the header optional and sends the default when the caller omits it: +### Default values + +Set a client-side default value on a global header using [`x-fern-default`](/learn/api-definitions/openapi/extensions/default). The generated SDK makes the header optional and sends the default when the caller omits it: ```yaml {4} title="openapi.yml" x-fern-global-headers: @@ -39,6 +44,8 @@ x-fern-global-headers: x-fern-default: "2024-02-08" ``` +## In `generators.yml` + Alternatively, you can add headers to the [`api` block in your `generators.yml` file](/learn/sdks/reference/generators-yml#headers): ```yaml title="generators.yml" diff --git a/fern/products/sdks/deep-dives/configure-global-headers.mdx b/fern/products/sdks/deep-dives/configure-global-headers.mdx index 6a74b2a6b..58b523088 100644 --- a/fern/products/sdks/deep-dives/configure-global-headers.mdx +++ b/fern/products/sdks/deep-dives/configure-global-headers.mdx @@ -47,6 +47,8 @@ headers: +You can also pin a [default value](/learn/api-definitions/openapi/extensions/default) on a global header so the SDK sends it automatically when the caller doesn't provide one. + For full configuration details, see the docs for your API definition format: diff --git a/fern/products/sdks/deep-dives/generated-sdk.mdx b/fern/products/sdks/deep-dives/generated-sdk.mdx index 1a36255f0..971fd8ce9 100644 --- a/fern/products/sdks/deep-dives/generated-sdk.mdx +++ b/fern/products/sdks/deep-dives/generated-sdk.mdx @@ -49,7 +49,7 @@ When you define webhooks in your API spec, Fern automatically [generates utiliti ## Default parameter values -You can configure [default values](/learn/api-definitions/openapi/extensions/default) for path, header, and query parameters. The SDK makes those parameters optional and sends the default when the caller doesn't provide one — useful for things like pinning an API version header or default region. Supported in TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs. +You can configure [default values](/learn/api-definitions/openapi/extensions/default) for path, header, and query parameters, including headers defined under [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers). The SDK makes those parameters optional and sends the default when the caller doesn't provide one — useful for things like pinning an API version header or default region. Supported in TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs. ## Customization options From f5a22496c48d668a2be8778cbfba6acf9cccbf16 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 27 Apr 2026 17:52:43 -0400 Subject: [PATCH 8/8] fix broken links --- fern/products/api-def/openapi/extensions/global-headers.mdx | 4 +++- fern/products/sdks/deep-dives/configure-global-headers.mdx | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/fern/products/api-def/openapi/extensions/global-headers.mdx b/fern/products/api-def/openapi/extensions/global-headers.mdx index 898b669e7..d684a1b42 100644 --- a/fern/products/api-def/openapi/extensions/global-headers.mdx +++ b/fern/products/api-def/openapi/extensions/global-headers.mdx @@ -35,7 +35,7 @@ x-fern-global-headers: ### Default values -Set a client-side default value on a global header using [`x-fern-default`](/learn/api-definitions/openapi/extensions/default). The generated SDK makes the header optional and sends the default when the caller omits it: +Set a client-side default value on a global header using [`x-fern-default`](/learn/api-definitions/openapi/extensions/default-values). The generated SDK makes the header optional and sends the default when the caller omits it: ```yaml {4} title="openapi.yml" x-fern-global-headers: @@ -60,6 +60,8 @@ api: type: optional ``` +## Generated SDK behavior + Both configurations yield the following client code: ```python diff --git a/fern/products/sdks/deep-dives/configure-global-headers.mdx b/fern/products/sdks/deep-dives/configure-global-headers.mdx index 58b523088..f9aebfa2b 100644 --- a/fern/products/sdks/deep-dives/configure-global-headers.mdx +++ b/fern/products/sdks/deep-dives/configure-global-headers.mdx @@ -47,7 +47,7 @@ headers: -You can also pin a [default value](/learn/api-definitions/openapi/extensions/default) on a global header so the SDK sends it automatically when the caller doesn't provide one. +You can also pin a [default value](/learn/api-definitions/openapi/extensions/default-values) on a global header so the SDK sends it automatically when the caller doesn't provide one. For full configuration details, see the docs for your API definition format: