Last updated 1 month ago

Replace server URL in different environments

Redocly allows you to use custom decorators to modify content in the API definition during the bundling process.

This page describes how to replace the server URL with a decorator for a given environment.

Step 1: Create a custom plugin

In this step, you will create a custom plugin and define the decorator dependency.

  1. Create a demo-plugin.js file with this information.
const ReplaceServersURL = require('./decorators/replace-servers-url');
const id = 'demo';

/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
const decorators = {
  oas3: {
    'replace-servers-url': ReplaceServersURL,

module.exports = {
  1. Save the demo-plugin.js file in a directory called plugins.
You can name the plugins directory anything you want. Make sure you use the correct name in the .redocly.yaml file (Step 4).

Step 2: Add a decorator and associate it with an environment variable

In this step, you will add a decorator and define the environment variable associated with it.

  1. Create a replace-servers-url.js file with this information.
module.exports = ReplaceServersURL;

/** @type {import('@redocly/openapi-cli').OasDecorator} */

function ReplaceServersURL() {
  return {
    Server: {
      leave(Server) {

        if ( 'SERVERS_URL' in process.env) {
          Server.url = process.env.SERVERS_URL;


SERVERS_URL is the environment variable to be defined in the API version settings.

  1. Save the replace-servers-url.js file in a directory called decorators.
You can name the decorators directory anything you want. Make sure you use the correct directory name in the demo-plugin.js file (Step 1).

Step 3: Add an environment variable

In this step, add the environment variable SERVERS_URL (defined in the previous step) to your API's version settings.

  1. In your Redocly app, navigate to API Registry > API Version > Settings > Environment variables.

Environment variables

  1. Select Add Variable to add a new environment variable. The Add a new environment variable dialog opens.

Add new environment variable

  1. Under Name, type in SERVERS_URL. Type in the value for the variable, and select Create Variable. The environment variable is now added to your API version settings.

Environment variables

To create API versions for different server URLs, use the API registry. Add another version of the API with a different environment variable value.

Step 4: Register the plugin for Redocly use

To use the decorator, you will need to register your plugin in your .redocly.yaml file. Register your plugins and decorators within the lint section.

# See for more information.
  main: openapi/openapi.yaml
    - recommended
    - './plugins/demo-plugin.js'
    # The key below is the combination of the plugin id (demo) and decorator name (replace-servers-url) defined in step 1 with a forward slash separator.
    demo/replace-servers-url: error

  htmlTemplate: ./docs/index.html
        main: "#32329f"

When you bundle the API, the decorator will replace the server's URL, if you've set the SERVERS_URL environment variable.