Document x-fern-default extension

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

fern/products/api-def/openapi/extensions/default.mdx

@@ -0,0 +1,77 @@
+---
+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, 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.
+
+<Note title="Supported languages">
+  `x-fern-default` is supported for TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs.
+</Note>
+
+## Path parameters
+
+In the example below, the SDK sends `us-east-1` for `region` when the caller doesn't specify one.
+
+```yaml {9} 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
+
+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:
+  /users:
+    get:
+      operationId: list_users
+      parameters:
+        - name: X-API-Version
+          in: header
+          x-fern-default: "2024-02-08"
+          schema:
+            type: string
+```
+
+## Query parameters
+
+In the example below, the SDK sends `false` for `verbose` when the caller doesn't specify one.
+
+```yaml {8} title="openapi.yml"
+paths:
+  /search:
+    get:
+      operationId: search
+      parameters:
+        - name: verbose
+          in: query
+          x-fern-default: false
+          schema:
+            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"
+```
+

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,10 +28,24 @@ x-fern-global-headers:
   - header: userpool_id
     optional: true
 ```
+
 <Note>
   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).
 </Note>
 
+### Default values
+
+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"
+```
+
+## 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"
@@ -44,6 +60,8 @@ api:
         type: optional<string>
 ```
 
+## Generated SDK behavior
+
 Both configurations yield the following client code:
 
 ```python

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 |

fern/products/sdks/deep-dives/configure-global-headers.mdx

@@ -47,6 +47,8 @@ headers:
 </Tab>
 </Tabs>
 
+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:
 
 <CardGroup cols={2}>

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
+
+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
 
 Your SDK users can configure individual requests using language-specific options: