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 receives a context parameter and returns request values. The context parameter provides information about the current operation and user, which you can use to dynamically configure request values.
Context Parameter
The context parameter includes:
userClaims
: Information about the authenticated user (optional)operation
: Details about the current API operationname
: Operation namepath
: API pathoperationId
: Operation ID (optional)href
: Operation URL (optional)method
: HTTP method
Here's an example showing how to use context to configure request values:
export function configure(context: {
userClaims?: UserClaims;
operation: {
name: string;
path: string;
operationId?: string;
href?: string;
method: string;
};
}) {
const requestValues: ConfigureRequestValues = {
headers: {
'API-Key': 'your-api-key',
// Use operation details to set custom headers
'Operation-ID': context.operation.operationId || '',
'Request-Method': context.operation.method
},
query: {
// Set different limits based on the operation
limit: context.operation.path.includes('users') ? '20' : '10',
offset: '0'
},
// Use authenticated user information if available
body: context.userClaims ? {
userId: context.userClaims.name,
email: context.userClaims.email
} : {
name: 'John Doe',
email: 'john@example.com'
}
};
return { requestValues };
}
You can use the context to:
- Set different values based on the operation being called
- Include user-specific information in requests
- Customize security tokens based on the endpoint
- Apply different configurations for different HTTP methods
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
The merging behavior ensures that configured values work within the constraints of your OpenAPI description while allowing dynamic updates.
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.