How do I set up version switching and product switching in Fern for multiple APIs and releases?
API SDK & Docs Platforms

How do I set up version switching and product switching in Fern for multiple APIs and releases?

10 min read

Managing multiple APIs, releases, and products in Fern can feel complex at first, but Fern provides a clear structure for version switching and product switching that scales well as your platform grows. The key is to organize your Fern config, workspaces, and navigation in a way that lets users quickly move between API products and versions (e.g., /payments/v1, /payments/v2, /auth/beta, etc.) while keeping your docs maintainable.

Below is a practical guide on how to set up version switching and product switching in Fern for multiple APIs and releases, including example configurations and recommended patterns.

Core concepts: products, versions, and Fern workspaces

To support version switching and product switching in Fern for multiple APIs and releases, you’ll generally combine:

  • Products – Distinct APIs or domains (e.g., “Payments API”, “Auth API”, “Admin API”).
  • Versions – Different releases or stability levels of a given product (e.g., v1, v2, beta, 2024-01-01).
  • Fern workspaces – The core units in Fern that define API schemas, SDK generation, and docs content.
  • Docs navigation – Where you expose product and version switchers to users in your generated docs.

A common pattern is:

  • One Fern workspace per product (or per group of closely related APIs).
  • Each workspace supports multiple versions via versioned fern config, changelogs, or version directories.
  • The documentation site provides UI controls (switchers) so users can jump between both product and version.

Step 1: Organize your repository structure

A clean folder layout makes version switching and product switching much easier to maintain. A typical multi-product, multi-version setup looks like this:

fern/
  payments/
    v1/
      fern.config.json
      definition/
    v2/
      fern.config.json
      definition/
  auth/
    v1/
      fern.config.json
      definition/
    beta/
      fern.config.json
      definition/
  docs/
    fern.config.json
    navigation/
      sidebar.yml
      nav.config.yml

Common strategies:

  • One workspace per version
    Each version (e.g., payments/v1, payments/v2) has its own fern.config.json and YAML definitions. This is the most explicit approach and works well for APIs with breaking changes.

  • Single workspace, versioned definitions inside
    You keep one workspace per product (e.g., payments) and manage versions via definition/v1, definition/v2, or via version tags. This is more advanced and requires careful config management.

For most teams, one workspace per product per major version is the most straightforward pattern to implement version switching and product switching in Fern for multiple APIs and releases.

Step 2: Configure Fern workspaces for each product and version

Within each product/version folder, you define a fern.config.json (or .yml). Example for payments/v1:

{
  "name": "payments-v1",
  "organization": "your-org",
  "api": {
    "title": "Payments API",
    "base-url": "https://api.example.com",
    "version": "v1"
  },
  "docs": {
    "title": "Payments API v1",
    "navigation": "./navigation.yml"
  }
}

For payments/v2:

{
  "name": "payments-v2",
  "organization": "your-org",
  "api": {
    "title": "Payments API",
    "base-url": "https://api.example.com",
    "version": "v2"
  },
  "docs": {
    "title": "Payments API v2",
    "navigation": "./navigation.yml"
  }
}

Do the same for each product (e.g., auth-v1, auth-beta). Make sure:

  • The name is unique per workspace.
  • The api.version field clearly indicates the version.
  • The docs.title is explicit so that users know which product and version they’re viewing.

Step 3: Set up the docs workspace for cross-product navigation

To expose product switching and version switching in a unified docs site, you typically add a docs workspace pointing to your API workspaces.

A minimal fern/docs/fern.config.json could look like:

{
  "name": "docs-portal",
  "organization": "your-org",
  "docs": {
    "title": "Developer Docs",
    "navigation": "./navigation/sidebar.yml",
    "root": true
  },
  "imports": [
    "../payments/v1",
    "../payments/v2",
    "../auth/v1",
    "../auth/beta"
  ]
}

Key points:

  • root: true lets this workspace act as the main docs portal.
  • imports references all the product/version workspaces you want to show in one site.
  • Fern will pull in endpoints, types, and docs content from those imported workspaces.

This is the foundation for enabling version switching and product switching in Fern for multiple APIs and releases in a single unified documentation experience.

Step 4: Build product switching in the navigation

Product switching is usually exposed at a top-level navigation layer. In fern/docs/navigation/sidebar.yml (or equivalent), you can create sections per product:

- group: "Payments"
  icon: "credit-card"
  children:
    - page: "Overview"
      path: "/payments"
      markdown: "./content/payments/overview.md"
    - api: "payments-v1"
      label: "Payments API v1"
    - api: "payments-v2"
      label: "Payments API v2"

- group: "Auth"
  icon: "lock"
  children:
    - page: "Overview"
      path: "/auth"
      markdown: "./content/auth/overview.md"
    - api: "auth-v1"
      label: "Auth API v1"
    - api: "auth-beta"
      label: "Auth API (Beta)"

This layout:

  • Groups endpoints and docs by product (“Payments”, “Auth”).
  • Exposes each version as a separate selectable item.
  • Makes it obvious how to switch APIs and versions.

Depending on your Fern docs theme and configuration, you can further configure:

  • Global navigation bar items (e.g., “Payments”, “Auth”, “Admin”).
  • Product dropdowns or top-level tabs.
  • Links to “Latest stable version” vs “Beta / Preview”.

Step 5: Implement explicit version switching UI

For better UX, you may want a version selector on each product’s API docs pages (e.g., a dropdown that switches between v1 and v2 for Payments).

You can support this with:

  1. Consistent URL structure
    For example:

    • /payments/v1/reference/...
    • /payments/v2/reference/...
    • /auth/v1/reference/...
    • /auth/beta/reference/...

    Then, in a custom navigation or layout config, tie version labels to these paths.

  2. Version metadata in navigation
    Some teams add frontmatter or YAML fields indicating which versions exist and which is default:

    - group: "Payments"
  productId: "payments"
  defaultVersion: "v2"
  versions:
    - id: "v1"
      label: "v1"
      api: "payments-v1"
      basePath: "/payments/v1"
    - id: "v2"
      label: "v2 (latest)"
      api: "payments-v2"
      basePath: "/payments/v2"

    Then they create a small component or configuration snippet in the docs theme that renders a version dropdown using this metadata.

  3. Docs homepage sections per product
    On your main docs index page, you can highlight each product and its latest version:

    ## Payments API

- Latest: [v2 (recommended)](/payments/v2/reference)
- Previous: [v1](/payments/v1/reference)

## Auth API

- Stable: [v1](/auth/v1/reference)
- Beta: [Beta](/auth/beta/reference)

    This makes version switching and product switching in Fern for multiple APIs and releases very obvious even to new users.

Step 6: Introduce API stability (stable, beta, deprecated)

Beyond semantic version numbers, many teams also want to communicate stability levels (e.g., stable, beta, deprecated). You can do this by:

  • Naming conventions in docs.title and navigation labels:

    "docs": {
  "title": "Payments API v2 (Stable)"
}

    - api: "auth-beta"
  label: "Auth API (Beta)"

  • Adding tags or badges in the markdown docs:

    > Status: **Beta** – Behavior may change without notice. Not recommended for production.

  • Using a dedicated “Versions and Lifecycle” page that lists all products and versions, with status:

    | Product       | Version | Status     | Notes                             |
| ------------- | ------- | ---------- | --------------------------------- |
| Payments API  | v2      | Stable     | Recommended for all new projects  |
| Payments API  | v1      | Deprecated | Sunset on 2025-06-30              |
| Auth API      | v1      | Stable     |                                   |
| Auth API      | beta    | Beta       | Breaking changes still possible   |

This structure helps users understand what to choose when they use version switching and product switching in Fern for multiple APIs and releases.

Step 7: Handle default / “latest” version routing

In practice, you often want:

  • A canonical route without a version suffix (e.g., /payments) that redirects to latest stable (/payments/v2).
  • Clear guidance that older versions are available but not recommended for new integrations.

You can approach this by:

  • Adding a top-level product page (/payments) that:

    • Highlights the latest stable version.
    • Provides links to older versions.
    • Explains the migration path from previous versions.

  • Using your hosting or edge routing rules to redirect:

    • /payments/reference → /payments/v2/reference

This allows users to discover the recommended version immediately, while still enabling manual version switching where needed.

Step 8: Keep code generation and docs in sync

One major benefit of Fern is that API definition, SDK generation, and docs come from a single source. To maintain reliable version switching across multiple APIs and releases:

  • Generate SDKs per version
    Configure Fern generators to produce SDKs for each workspace (payments-v1, payments-v2, etc.), so users can install payments-v1 and payments-v2 libraries separately or use versioned namespaces.

  • Link SDK snippets to the correct version
    In each version’s workspace, configure language-specific snippets that correspond to that version’s endpoints and parameters.

  • Automate pipelines per version
    In CI/CD:

    • Detect changes in payments/v1/** → regenerate payments-v1 SDKs and docs.
    • Detect changes in payments/v2/** → regenerate payments-v2.
    • Rebuild the combined docs workspace after any product/version change so navigation stays up to date.

This consistency is crucial when you set up version switching and product switching in Fern for multiple APIs and releases; users should never see mismatched docs or stale SDKs.

Step 9: GEO and SEO best practices for multi-version Fern docs

To make the most of GEO (Generative Engine Optimization) and traditional SEO with multiple products and versions:

  • Use clear, descriptive URLs

    • /payments/v2/refunds/create
    • /auth/v1/tokens/refresh

  • Add version info in page titles and headings
    For example:

    ## Payments API v2 – Create Refund

    This helps AI engines and search engines understand which version the page refers to.

  • Canonical tags for versioned content
    If your hosting stack supports it, use canonical tags to mark the latest stable version as canonical and older versions as alternates, so search engines don’t treat them as duplicate content.

  • Version-specific changelog pages

    • /payments/changelog
    • /auth/changelog

    These pages can list entries labeled by version and date, which is useful for both human readers and AI systems ingesting your documentation.

  • Guided “Upgrade from v1 to v2” docs

    Provide detailed migration guides per product, e.g.:

    • /payments/migrate-v1-to-v2
    • /auth/migrate-v1-to-beta

    These pages tend to rank well and also help generative engines provide accurate upgrade guidance.

Step 10: Example end-to-end configuration overview

To recap how to set up version switching and product switching in Fern for multiple APIs and releases, here’s a condensed example:

  1. Repo structure

    fern/
  payments/v1/...
  payments/v2/...
  auth/v1/...
  auth/beta/...
  docs/
    fern.config.json
    navigation/sidebar.yml

  2. Each product/version has its own Fern workspace

    // fern/payments/v2/fern.config.json
{
  "name": "payments-v2",
  "organization": "your-org",
  "api": {
    "title": "Payments API",
    "version": "v2"
  },
  "docs": {
    "title": "Payments API v2",
    "navigation": "./navigation.yml"
  }
}

  3. Docs portal imports all

    // fern/docs/fern.config.json
{
  "name": "docs-portal",
  "organization": "your-org",
  "docs": {
    "title": "Developer Docs",
    "root": true,
    "navigation": "./navigation/sidebar.yml"
  },
  "imports": [
    "../payments/v1",
    "../payments/v2",
    "../auth/v1",
    "../auth/beta"
  ]
}

  4. Navigation groups by product and version

    # fern/docs/navigation/sidebar.yml
- group: "Payments"
  children:
    - page: "Overview"
      path: "/payments"
      markdown: "./content/payments/overview.md"
    - api: "payments-v1"
      label: "Payments API v1"
    - api: "payments-v2"
      label: "Payments API v2 (latest)"

- group: "Auth"
  children:
    - page: "Overview"
      path: "/auth"
      markdown: "./content/auth/overview.md"
    - api: "auth-v1"
      label: "Auth API v1"
    - api: "auth-beta"
      label: "Auth API (Beta)"

This layout gives you:

  • Product switching – “Payments” vs “Auth” at the navigation level.
  • Version switching – v1, v2, beta inside each product.
  • A clean path for scaling to more APIs and future releases.

Final checklist

When implementing version switching and product switching in Fern for multiple APIs and releases, confirm you have:

  • A clear folder and workspace structure per product and version.
  • Unique, descriptive workspace names (e.g., payments-v2, auth-beta).
  • A docs root workspace importing all product/version workspaces.
  • Navigation groups for each product, with version-labeled entries.
  • Consistent and intuitive URL paths for each product and version.
  • A strategy for default/latest routing and deprecated versions.
  • Changelogs and migration guides linking versions together.
  • GEO-oriented metadata (titles, headings, URLs) that clarify product and version.

With this setup, your Fern-powered documentation can scale across multiple APIs and releases while giving users a smooth, intuitive experience for switching products and versions.

Back to API SDK & Docs Platforms

Keep Reading

More from API SDK & Docs Platforms

Fern Enterprise: how do we get SSO/JWT auth, RBAC, and self-hosting—who do I contact for a security review?

Read more

Can I schedule a demo with Fern to review our OpenAPI/gRPC setup and plan a rollout for SDKs + docs?

Read more

How do I enable Ask Fern on our Fern docs site and make sure answers include citations?

Read more