docs: add documentation for x-fern-sdk-variables extension

[devin-ai-integration]

Document x-fern-sdk-variables OpenAPI extension

Summary

This PR adds comprehensive documentation for the x-fern-sdk-variables OpenAPI extension, which allows defining common path parameters at the document level. These variables (like tenant IDs or environment identifiers) are set once during SDK client initialization rather than passed to each method call.

Changes:

• Created new documentation page at /openapi/extensions/sdk-variables with configuration examples and SDK usage patterns for TypeScript, Python, and Java
• Added navigation entry in api-def.yml for sidebar visibility
• Updated extensions overview page to include the new extension in the available extensions table
• Documented minimum versions: TypeScript 2.6.3+, Python 4.24.0+, Java 3.6.3+
• Used plant-themed examples (gardens, plants, zones) per content guidelines
• Added syntax highlighting to emphasize x-fern-sdk-variables and x-fern-sdk-variable extensions

Review & Testing Checklist for Human

• ⚠️ CRITICAL: Verify documented behavior through actual SDK generation - The documentation was written based on code research in fern-api/fern, NOT by actually generating and testing SDKs. Create a test OpenAPI spec with the documented configuration and generate SDKs for TypeScript, Python, and Java to confirm: (1) variables appear as required constructor parameters, (2) variables are NOT method parameters, (3) variables are correctly injected into path parameters in HTTP requests, (4) the code examples match actual generated code structure.

• Verify minimum version numbers - The versions (TypeScript 2.6.3, Python 4.24.0, Java 3.6.3) were determined through git history research. Python 4.24.0 has an explicit changelog entry, but TypeScript/Java versions were inferred from bug fix commits. Consider testing with earlier versions to confirm they lack support, or check release notes/changelogs to confirm these are the first versions with the feature.

• Test the string-only limitation - The documentation states SDK variables only support string types based on code in getVariableDefinitions.ts that checks schema.type === "string". Verify this by attempting to define variables with other types (integer, boolean, object) and confirming they're rejected with the documented error message.

• Test navigation and links after deployment - Verify the sidebar link works correctly and the link from /learn/api-definitions/openapi/extensions/overview navigates to the new SDK variables page at the correct URL.

Recommended test plan

Create a minimal OpenAPI spec to validate the documented behavior:

openapi: 3.0.0
info:
  title: Test API
  version: 1.0.0

x-fern-sdk-variables:
  gardenId:
    type: string

paths:
  /gardens/{gardenId}/plants:
    get:
      parameters:
        - name: gardenId
          in: path
          required: true
          x-fern-sdk-variable: gardenId
          schema:
            type: string
      responses:
        '200':
          description: Success

Generate SDKs for all three languages and verify the behavior matches the documentation examples.

Notes

• Documentation written based on research of fern-api/fern implementation (OpenAPI parser at packages/cli/api-importers/openapi/openapi-ir-parser/src/openapi/v3/extensions/, IR definitions, and TypeScript/Python/Java generator code)
• The string-only limitation is enforced by the OpenAPI importer; the IR itself supports any TypeReference but the OpenAPI parser currently only accepts string types
• Code highlighting emphasizes the extension names to help users identify the key configuration elements
• Link to Devin session: https://app.devin.ai/sessions/c431328b5b1848658e791fd897a83ced
• Requested by: thomas@buildwithfern.com (@tjb9dc)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

🌿 Preview your docs: https://fern-preview-f18c8b0c-487e-474f-997f-71cabe63e1e5.docs.buildwithfern.com/learn

[github-actions]

🌿 Preview your docs: https://fern-preview-7354c8b8-133b-4f8f-a2f8-dbc450621c52.docs.buildwithfern.com/learn

[github-actions]

🌿 Preview your docs: https://fern-preview-9fea0e11-8eeb-4e34-bc3e-1fd4cda7e508.docs.buildwithfern.com/learn

[github-actions]

🌿 Preview your docs: https://fern-preview-a31437b9-a696-4f81-9367-abd8a43eb76f.docs.buildwithfern.com/learn

[github-actions]

🌿 Preview your docs: https://fern-preview-e8541676-9137-44db-9a61-60283e25fc6d.docs.buildwithfern.com/learn

[github-actions]

🌿 Preview your docs: https://fern-preview-9095590c-63d3-4856-aa40-a72e9a1d0bdd.docs.buildwithfern.com/learn

[github-actions]

🌿 Preview your docs: https://fern-preview-788bf509-e8e5-44c2-be1d-42dda14f9874.docs.buildwithfern.com/learn