Replace servers URL in different environments

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

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

Prerequisites

We do, You do

This tutorial is most effective when you follow along and complete the steps.

Install @redocly/cli with version 1.0.0-beta.111 or later (we use 1.0.0-beta.111 in this tutorial).

Save the following OpenAPI file as original.yaml into a new directory named replace-servers-demo.

openapi: 3.1.0
info:
  version: 1.0.0
  title: Custom decorators demo
  description: The servers URL is replaced by the decorator during the `bundle` process.
servers:
  - url: 'https://example.com/api/v1'
paths:
  /status:
    get:
      summary: Get status
      operationId: getStatus
      security: []
      responses:
        '204':
          description: Status OK
        '400':
          description: Status not OK

Use your favorite IDE for editing files (we use VS Code and have the Redocly extension installed).

Step 1: Create a custom plugin

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

Create a directory called plugins.
Create a plugin.js file inside of the plugins directory with this information.

const ReplaceServersURL = require('./decorators/replace-servers-url');
const id = 'plugin';

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

module.exports = {
  id,
  decorators,
};

Save the file.

You can name the plugins directory and file anything you want. Make sure you use the correct name in the Redocly configuration file (Step 3).

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

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

Create a directory decorators inside of the plugins directory.
Create a replace-servers-url.js file with this information and save it inside of the decorators directory.

module.exports = ReplaceServersURL;

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

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

        if (serverUrl) {
          Server.url = serverUrl;
        }

      }
    }
  }
};

You can name the decorators directory anything you want. Make sure you use the correct directory name in line 1 of the plugin.js file (Step 1).

Step 3: Configure the plugin for use

To use the decorator, register your plugin in your Redocly configuration file. Register your plugins and decorators.

apis:
  sample@v1-backend:
    root: original.yaml
    decorators:
      plugin/replace-servers-url:
        serverUrl: 'https://backend.example.com/v1'
  sample@v1-proxy:
    root: original.yaml
    decorators:
      plugin/replace-servers-url:
        serverUrl: 'https://proxy.example.com/v1'
plugins:
  - './plugins/plugin.js'
extends:
  - recommended

Step 4: Verify the output

The following command bundles the original.yaml API with the "backend" server URL.

npx @redocly/cli bundle sample@v1-backend

The output should show the correct server URL.

openapi: 3.1.0
info:
  version: 1.0.0
  title: Custom decorators demo
  description: The servers URL is replaced by the decorator during the `bundle` process.
servers:
  - url: https://backend.example.com/v1
# ...

The following command bundles the original.yaml API with the "proxy" server URL.

npx @redocly/cli bundle sample@v1-proxy