From 60f92f8a4b8f02993c0ea8fd364bab5d57c7bdea Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:41:37 +0000 Subject: [PATCH 1/7] docs: add documentation for x-fern-sdk-variables extension Co-Authored-By: thomas@buildwithfern.com --- .../openapi-pages/extensions/overview.md | 1 + .../extensions/sdk-variables.mdx | 169 ++++++++++++++++++ 2 files changed, 170 insertions(+) create mode 100644 fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx diff --git a/fern/products/api-def/openapi-pages/extensions/overview.md b/fern/products/api-def/openapi-pages/extensions/overview.md index 76c1385b..f2a56516 100644 --- a/fern/products/api-def/openapi-pages/extensions/overview.md +++ b/fern/products/api-def/openapi-pages/extensions/overview.md @@ -26,6 +26,7 @@ The table below shows all available extensions and links to detailed documentati | [`x-fern-ignore`](./ignoring-elements) | Skip reading specific endpoints or schemas | | [`x-fern-sdk-method-name`](./method-names) | Customize SDK method names | | [`x-fern-sdk-group-name`](./method-names) | Organize methods into SDK groups | +| [`x-fern-sdk-variables`](./sdk-variables) | Set common path parameters across all requests | | [`x-fern-parameter-name`](./parameter-names) | Customize parameter variable names | | [`x-fern-property-name`](./property-names) | Customize object property variable names | | [`x-fern-type-name`](./schema-names) | Override auto-generated names for inline schemas | diff --git a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx new file mode 100644 index 00000000..0ef63054 --- /dev/null +++ b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx @@ -0,0 +1,169 @@ +--- +title: SDK variables +description: Use `x-fern-sdk-variables` to set common path parameters across all requests +--- + +The `x-fern-sdk-variables` extension allows you to define variables that are set once during SDK client initialization and automatically used in path parameters across all endpoint calls. This is particularly useful for common path parameters like tenant IDs, organization IDs, or environment identifiers that appear in many endpoint paths. + +## How it works + +SDK variables are defined at the document level using `x-fern-sdk-variables` and then referenced in path parameters using `x-fern-sdk-variable`. When a path parameter is marked as a variable, it becomes a required parameter in the SDK client constructor instead of being passed to individual endpoint methods. + +## Configuration + +### Define variables + +At the document level, define your variables with their types: + +```yaml title="openapi.yml" +openapi: 3.0.0 +info: + title: Plant API + version: 1.0.0 + +x-fern-sdk-variables: + gardenId: + type: string + description: The unique identifier for your garden +``` + +### Reference variables in path parameters + +Mark path parameters as variables using `x-fern-sdk-variable`: + +```yaml {9} +paths: + /gardens/{gardenId}/plants: + get: + operationId: list_plants + parameters: + - name: gardenId + in: path + required: true + x-fern-sdk-variable: gardenId + schema: + type: string + responses: + '200': + description: List of plants +``` + +## Generated SDK behavior + +### TypeScript + +With SDK variables configured, the TypeScript SDK requires the variable in the client constructor: + +```typescript +import { PlantClient } from "@acme/plant-api"; + +const client = new PlantClient({ + gardenId: "garden_123", + apiKey: "your-api-key" +}); + +// gardenId is automatically included in the request +const plants = await client.listPlants(); +``` + +Without SDK variables, the parameter would be required on each method call: + +```typescript +// Without x-fern-sdk-variables +const plants = await client.listPlants("garden_123"); +``` + +### Python + +In Python SDKs, variables are required constructor parameters: + +```python +from acme import PlantClient + +client = PlantClient( + garden_id="garden_123", + api_key="your-api-key" +) + +# garden_id is automatically included in the request +plants = client.list_plants() +``` + +### Java + +In Java SDKs, variables are set using builder methods: + +```java +PlantClient client = PlantClient.builder() + .gardenId("garden_123") + .apiKey("your-api-key") + .build(); + +// gardenId is automatically included in the request +List plants = client.listPlants(); +``` + +## Multiple variables + +You can define multiple SDK variables for complex path hierarchies: + +```yaml title="openapi.yml" +x-fern-sdk-variables: + gardenId: + type: string + description: The unique identifier for your garden + zoneId: + type: string + description: The zone within the garden + +paths: + /gardens/{gardenId}/zones/{zoneId}/plants: + get: + operationId: list_plants_in_zone + parameters: + - name: gardenId + in: path + required: true + x-fern-sdk-variable: gardenId + schema: + type: string + - name: zoneId + in: path + required: true + x-fern-sdk-variable: zoneId + schema: + type: string +``` + +This generates an SDK where both variables are set during initialization: + +```typescript +const client = new PlantClient({ + gardenId: "garden_123", + zoneId: "zone_456", + apiKey: "your-api-key" +}); + +const plants = await client.listPlantsInZone(); +``` + +## Use cases + +SDK variables are ideal for: + +- **Multi-tenant APIs**: Set the tenant or organization ID once during client initialization +- **Environment-specific paths**: Configure environment identifiers (production, staging) at the client level +- **Hierarchical resources**: Set parent resource IDs that are used across many child resource endpoints +- **Regional APIs**: Configure region identifiers that appear in all endpoint paths + +## Supported languages + +SDK variables are supported in the following Fern SDK generators: + +- TypeScript (v3.13.0+) +- Python (v4.32.1+) +- Java (v3.10.1+) + + + SDK variables only support string types. If you need more complex types, consider using global headers with `x-fern-global-headers` instead. + From da4e7d64d0f122f55d9a9ad47fd9a6b0d7ecfaa4 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 19:12:43 +0000 Subject: [PATCH 2/7] docs: add sdk-variables to navigation sidebar Co-Authored-By: thomas@buildwithfern.com --- fern/products/api-def/api-def.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index 1e579e6c..846bc659 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -58,6 +58,8 @@ navigation: - page: SDK method names path: ./openapi-pages/extensions/method-names.mdx slug: method-names + - page: SDK variables + path: ./openapi-pages/extensions/sdk-variables.mdx - page: Tag display names path: ./openapi-pages/extensions/tag-display-name.mdx - page: Parameter names From 50b1239df3461fe9e6e1ff62654ba77a1444b108 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 20:49:12 +0000 Subject: [PATCH 3/7] docs: update sdk-variables minimum versions and remove inaccurate suggestion Co-Authored-By: thomas@buildwithfern.com --- .../api-def/openapi-pages/extensions/sdk-variables.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx index 0ef63054..02c3a1f7 100644 --- a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx +++ b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx @@ -160,10 +160,10 @@ SDK variables are ideal for: SDK variables are supported in the following Fern SDK generators: -- TypeScript (v3.13.0+) -- Python (v4.32.1+) -- Java (v3.10.1+) +- TypeScript (v2.6.3+) +- Python (v4.24.0+) +- Java (v3.6.3+) - SDK variables only support string types. If you need more complex types, consider using global headers with `x-fern-global-headers` instead. + SDK variables only support string types. From 996da5d4fa6053e16f51b7cae6ba6b996faa483c Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 21:08:54 +0000 Subject: [PATCH 4/7] docs: add green highlighting to x-fern-sdk-variables code blocks Co-Authored-By: thomas@buildwithfern.com --- .../api-def/openapi-pages/extensions/sdk-variables.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx index 02c3a1f7..4f3b1f0a 100644 --- a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx +++ b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx @@ -15,7 +15,7 @@ SDK variables are defined at the document level using `x-fern-sdk-variables` and At the document level, define your variables with their types: -```yaml title="openapi.yml" +```yaml {6-9} title="openapi.yml" openapi: 3.0.0 info: title: Plant API @@ -107,7 +107,7 @@ List plants = client.listPlants(); You can define multiple SDK variables for complex path hierarchies: -```yaml title="openapi.yml" +```yaml {1-8,18,24} title="openapi.yml" x-fern-sdk-variables: gardenId: type: string From 6f439c3bff1f8d8f53fc193930f51dd1ca8804c1 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 22:18:18 +0000 Subject: [PATCH 5/7] docs: update highlighting in Multiple variables section Co-Authored-By: thomas@buildwithfern.com --- .../products/api-def/openapi-pages/extensions/sdk-variables.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx index 4f3b1f0a..3cb7266e 100644 --- a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx +++ b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx @@ -107,7 +107,7 @@ List plants = client.listPlants(); You can define multiple SDK variables for complex path hierarchies: -```yaml {1-8,18,24} title="openapi.yml" +```yaml {1-7,17,23} title="openapi.yml" x-fern-sdk-variables: gardenId: type: string From b3715968b55063d98bb6c1417e5340723669fba8 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 4 Nov 2025 19:53:13 -0500 Subject: [PATCH 6/7] condense page --- .../extensions/sdk-variables.mdx | 147 ++++-------------- 1 file changed, 28 insertions(+), 119 deletions(-) diff --git a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx index 3cb7266e..7d9710b1 100644 --- a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx +++ b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx @@ -3,109 +3,15 @@ title: SDK variables description: Use `x-fern-sdk-variables` to set common path parameters across all requests --- -The `x-fern-sdk-variables` extension allows you to define variables that are set once during SDK client initialization and automatically used in path parameters across all endpoint calls. This is particularly useful for common path parameters like tenant IDs, organization IDs, or environment identifiers that appear in many endpoint paths. +The `x-fern-sdk-variables` extension allows you to define variables that are set once during SDK client initialization and automatically used in path parameters across all endpoint calls. This is useful for common parameters like tenant IDs, organization IDs, or environment identifiers that appear in many endpoint paths. -## How it works - -SDK variables are defined at the document level using `x-fern-sdk-variables` and then referenced in path parameters using `x-fern-sdk-variable`. When a path parameter is marked as a variable, it becomes a required parameter in the SDK client constructor instead of being passed to individual endpoint methods. - -## Configuration - -### Define variables - -At the document level, define your variables with their types: - -```yaml {6-9} title="openapi.yml" -openapi: 3.0.0 -info: - title: Plant API - version: 1.0.0 - -x-fern-sdk-variables: - gardenId: - type: string - description: The unique identifier for your garden -``` - -### Reference variables in path parameters - -Mark path parameters as variables using `x-fern-sdk-variable`: - -```yaml {9} -paths: - /gardens/{gardenId}/plants: - get: - operationId: list_plants - parameters: - - name: gardenId - in: path - required: true - x-fern-sdk-variable: gardenId - schema: - type: string - responses: - '200': - description: List of plants -``` - -## Generated SDK behavior - -### TypeScript - -With SDK variables configured, the TypeScript SDK requires the variable in the client constructor: - -```typescript -import { PlantClient } from "@acme/plant-api"; - -const client = new PlantClient({ - gardenId: "garden_123", - apiKey: "your-api-key" -}); - -// gardenId is automatically included in the request -const plants = await client.listPlants(); -``` - -Without SDK variables, the parameter would be required on each method call: - -```typescript -// Without x-fern-sdk-variables -const plants = await client.listPlants("garden_123"); -``` - -### Python - -In Python SDKs, variables are required constructor parameters: - -```python -from acme import PlantClient - -client = PlantClient( - garden_id="garden_123", - api_key="your-api-key" -) - -# garden_id is automatically included in the request -plants = client.list_plants() -``` - -### Java - -In Java SDKs, variables are set using builder methods: - -```java -PlantClient client = PlantClient.builder() - .gardenId("garden_123") - .apiKey("your-api-key") - .build(); - -// gardenId is automatically included in the request -List plants = client.listPlants(); -``` + + SDK variables are supported in TypeScript (v2.6.3+), Python (v4.24.0+), and Java (v3.6.3+). Only string types are supported. + -## Multiple variables +## Usage -You can define multiple SDK variables for complex path hierarchies: +Define variables at the document level using `x-fern-sdk-variables`, then mark path parameters as variables using `x-fern-sdk-variable`: ```yaml {1-7,17,23} title="openapi.yml" x-fern-sdk-variables: @@ -135,9 +41,12 @@ paths: type: string ``` -This generates an SDK where both variables are set during initialization: +### SDK usage + +Variables become required constructor parameters instead of being passed to individual method calls: -```typescript + +```typescript {2-3} const client = new PlantClient({ gardenId: "garden_123", zoneId: "zone_456", @@ -147,23 +56,23 @@ const client = new PlantClient({ const plants = await client.listPlantsInZone(); ``` -## Use cases - -SDK variables are ideal for: - -- **Multi-tenant APIs**: Set the tenant or organization ID once during client initialization -- **Environment-specific paths**: Configure environment identifiers (production, staging) at the client level -- **Hierarchical resources**: Set parent resource IDs that are used across many child resource endpoints -- **Regional APIs**: Configure region identifiers that appear in all endpoint paths - -## Supported languages +```python {2-3} +client = PlantClient( + garden_id="garden_123", + zone_id="zone_456", + api_key="your-api-key" +) -SDK variables are supported in the following Fern SDK generators: +plants = client.list_plants_in_zone() +``` -- TypeScript (v2.6.3+) -- Python (v4.24.0+) -- Java (v3.6.3+) +```java {2-3} +PlantClient client = PlantClient.builder() + .gardenId("garden_123") + .zoneId("zone_456") + .apiKey("your-api-key") + .build(); - - SDK variables only support string types. - +List plants = client.listPlantsInZone(); +``` + From 6739893542d2e4604f2b11f1f5a89f6d5f2a295f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 4 Nov 2025 19:55:27 -0500 Subject: [PATCH 7/7] update headings --- .../api-def/openapi-pages/extensions/sdk-variables.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx index 7d9710b1..80931661 100644 --- a/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx +++ b/fern/products/api-def/openapi-pages/extensions/sdk-variables.mdx @@ -9,7 +9,7 @@ The `x-fern-sdk-variables` extension allows you to define variables that are set SDK variables are supported in TypeScript (v2.6.3+), Python (v4.24.0+), and Java (v3.6.3+). Only string types are supported. -## Usage +## Configuration Define variables at the document level using `x-fern-sdk-variables`, then mark path parameters as variables using `x-fern-sdk-variable`: @@ -41,7 +41,7 @@ paths: type: string ``` -### SDK usage +## SDK usage Variables become required constructor parameters instead of being passed to individual method calls: