Last updated 2 months ago

Enabling the version switcher in on-premise Reference docs

With Redocly, you can manage multiple versions of the same API definition and create API documentation for each of those versions. The version switcher drop-down in the generated API documentation lets you select a particular version to view associated documentation.

Version switcher menu

When using Reference docs on-premise, multiple versions of an API definition are not automatically detected when generating API documentation. As a result, you won't see the version switcher by default in your documentation.

This guide explains how to enable the version switcher by specifying the source file for each API version you want to display.

Prerequisites

Enable the version switcher

  1. Specify the source files for each version in the options.json file.

If you don't already have the options.json file, create a new one with the following contents:

{
  "definitions": {
    "versions": [
      { "title": "Version 3.1", "id": "v3.1", "url": "definition-v3.1.yaml" },
      { "title": "Version 2.1", "id": "v2.1", "url": "definition-v2.1.yaml" }
    ]
  },
  // examples of additional options
  "requiredPropsFirst": "true",
  "showConsole": "true"
}

The value of the "title" field is displayed in the version switcher drop-down as the name of each version. The version switcher displays the versions in the same order as they are listed in the options.json file.

To ensure that the documentation for a specific version is always loaded first, you can set that version as the default. Add "isDefault": true to the version like in the following example:

{ "title": "Version 3.1", "id": "v3.1", "url": "definition-v3.1.yaml", "isDefault": true },
{ "title": "Version 2.1", "id": "v2.1", "url": "definition-v2.1.yaml" }
  1. Pass the options.json file to the Redocly CLI tool.

The CLI tool collects the API definitions from the file, so you don't have to provide the path to any of the API definition files when running the command.

Before you run the command, replace VERSION with the number of the latest available Reference docs version.

npx @redocly/reference-docs@VERSION build --options options.json
  1. Confirm that the version switcher is enabled and functioning in your API documentation.

Access the documentation you've generated with Reference docs on-premise. By default, the version switcher is located in the upper left section of the page, above the navigation sidebar. Select an API documentation version in the drop-down and verify that it's correctly loaded.