Skip to content

Comments

docs: add server URL templating documentation to SDK design section#3672

Open
iamnamananand996 wants to merge 3 commits intomainfrom
devin/1771415548-server-url-templating-docs
Open

docs: add server URL templating documentation to SDK design section#3672
iamnamananand996 wants to merge 3 commits intomainfrom
devin/1771415548-server-url-templating-docs

Conversation

@iamnamananand996
Copy link
Member

@iamnamananand996 iamnamananand996 commented Feb 18, 2026

docs: add server URL templating page to SDK design section

Summary

Adds a new documentation page explaining the server URL templating feature under the "SDK design" section of the SDKs product docs. The page covers:

  • Configuring server variables in OpenAPI (servers block with variables, x-fern-default-url, x-server-name)
  • Multiple base URLs (endpoint-level servers with x-fern-server-name)
  • Generated SDK behavior with tabbed code examples for Python and Java
  • Equivalent Fern Definition config (api.yml with url-templates, default-urls, variables)
  • Language support table (Python and Java only)

Content was derived from reading the fern-api/fern repo: the OpenAPI test fixture at test-definitions/fern/apis/server-url-templating/openapi.yml, the IR schema types (ServerVariableSchema, SingleBaseUrlEnvironmentSchema, MultipleBaseUrlsEnvironmentSchema), seed-generated SDK outputs (seed/ts-sdk/server-url-templating/), and the v63-to-v62 IR migration.

Updates since last revision

  • Fixed vale lint warning: changed "they are" → "they're" in the intro paragraph.
  • Narrowed language support to Python and Java only per reviewer feedback. Removed TypeScript and Go code example tabs and updated the language support table accordingly.
  • Verified page renders correctly via local fern docs dev (tabs, tables, code highlighting, <Icon> components all display as expected).

Local preview of the server URL templating page

View original video (rec-4b70dc4e1858470bbf0f8f96382f415e-edited.mp4)

Review & Testing Checklist for Human

  • Fern Definition section accuracy (medium risk): The api.yml example with url-templates, default-urls, and variables was derived from internal schema types (MultipleBaseUrlsEnvironmentSchema). Confirm this is a valid user-facing config format and not just an internal representation populated during OpenAPI import.
  • x-server-name vs x-fern-server-name: The source OpenAPI fixture uses x-server-name at the top level and x-fern-server-name at the endpoint level. Verify the docs correctly explain when to use each.
  • Python/Java code examples: These were written to match the general pattern but were not verified against actual seed-generated output for those languages. Spot-check against seed/python-sdk/server-url-templating/ and seed/java-sdk/server-url-templating/.
  • Preview the page: Verify the preview deployment renders correctly end-to-end with the updated Python/Java-only content.

Notes

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>
@devin-ai-integration
Copy link
Contributor

🤖 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


Server URL templating lets you define base URLs with variable placeholders (e.g., `{region}`, `{environment}`) that SDK users can customize at runtime. This is useful for APIs deployed across multiple regions, environments, or custom domains.

Fern reads the standard OpenAPI `servers` block and generates SDK clients that accept these variables, falling back to sensible defaults when they are not provided.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'they're' instead of 'they are'.

@github-actions
Copy link
Contributor

github-actions bot commented Feb 18, 2026

devin-ai-integration bot and others added 2 commits February 18, 2026 12:01
Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>
Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

## Language support

Server URL templating is currently supported in the following generators:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant