Multiple versions for API reference docs

Prerequisites

1. You must have multiple versions of an API added to the registry.

Create reference docs

When you have multiple versions of an API, you will see an option to create multiple versions within your reference docs.

1. Select the versions you wish to display in the docs.
2. Select the default version, which loads when the docs are accessed without explicitly specifying a version.
3. Adjust any display labels. Your labels appear in the documentation select menu. The actual version appears within the docs URL in a path segment.
4. Order the versions using the drag handles to the order they will display within the select menu. Notice the top version doesn't need to be the default version.

The configurations shown above will result in the following version selection within the documentation.

The root url loads the default version.

Upon selecting another version with a display label that differs from the version name, the display label shows in the select menu and the version name displays in the URL.

You may deep link to any version. Switching versions will attempt to switch to the same operation of the different version, if it exists (or it will load the beginning of the docs).

Configuration settings

Redocly uses the Redocly configuration file associated with the default version as the metadata which will control the reference docs features and styles.

You may read all about the configuration file, or the docs-specific settings.

Recommended settings

We recommend settings to use with the multiple versions feature. These must be within your default version's configuration file.

Routing strategy

If you set your routing strategy to browser, the version will be accessed as a path segment instead of part of the hash fragment.

Browser routing strategy

With the browser routing strategy we see the version (v1 in this example) is part of the path: https://docs.example.com/v1/tag/User#operation/getUserByName.

Hash routing strategy

With the hash routing strategy we see the version (v1 in this example) is part of the hash fragment: https://docs.example.com/#v1/operation/getUserByName.

This excerpt from the Redocly configuration file sets the routing strategy to the browser type.

features.openapi:
  routingStrategy: browser
  layout:
    scope: section
# The routingStrategy "browser" must have a scoped layout, and we recommend "section" which is one html pre-rendered page per tag.

Edit multiple versions

Edit the versions displayed at any time from the docs' settings.