Configure request values

You can programmatically configure request values for your OpenAPI descriptions by ejecting and modifying the configure.ts file. This feature enables you to set default values for headers, query parameters, path parameters, cookies, and security details that merge with existing examples in your OpenAPI description.

Before you begin

Make sure you have the following:

• a redocly.yaml file located in the root directory of your project
• a basic understanding of TypeScript
• OpenAPI description files with examples

Eject configure.ts

To customize request values, first eject the configuration file:

npx @redocly/cli eject component ext/configure.ts

This command creates a local copy of configure.ts in your project's @theme folder.

Configure request values

The configure.ts file exports a configure function that returns request values. You can set values for:

• headers
• query parameters
• path parameters
• cookie parameters
• request body
• security details

The following example shows how to configure various request values:

export function configure() {
  const requestValues: ConfigureRequestValues = {
    headers: {
      'API-Key': 'your-api-key',
      'Custom-Header': 'custom-value'
    },
    query: {
      limit: '10',
      offset: '0'
    },
    path: {
      userId: '12345'
    },
    cookie: {
      session: 'abc123'
    },
    body: {
      name: 'John Doe',
      email: 'john@example.com'
    },
    security: {
      token: {
        access_token: 'your-access-token',
        token_type: 'Bearer'
      }
    }
  };

  return { requestValues };
}

Merge values

When you configure request values, they merge with existing examples in your OpenAPI description, rather than replacing them entirely. Here's how merging works:

Parameters

For headers, query parameters, path parameters, and cookies, configured values update the example field of matching parameters. The parameter must already exist in your OpenAPI description.

Request body

For request bodies, the configured values merge with existing example values:

• If the existing example is an object, properties are merged recursively.
• If the existing example is an array or primitive, it's replaced with the configured value.
• New properties are not added, only existing properties can be updated.

Security

Security values update the corresponding security scheme configurations:

• OAuth2: updates access token
• Basic Auth: updates username and password
• API Key: updates the token value

Example with merging

Consider this OpenAPI example:

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            example:
              name: "Alice Smith"
              email: "alice@example.com"
              settings:
                notifications: true
                theme: "light"

If you configure these request values:

export function configure() {
  return {
    requestValues: {
      body: {
        name: "Bob Wilson",
        settings: {
          notifications: false
        }
      }
    }
  };
}

The resulting merged example would be:

{
  "name": "Bob Wilson",
  "email": "alice@example.com",
  "settings": {
    "notifications": false,
    "theme": "light"
  }
}

Resources

• Learn how to Eject components of your Redocly project.