Skip to main content

Request Lifecycle & Handlers

OpenAPIBackend defines a rich set of hooks to intercept and control each step of the request lifecycle. Each handler receives the parsed Context object as the first argument, followed by any arguments passed to .handleRequest(), such as Express req, res, and next.

Built-in Lifecycle Handlers

These can be registered to hook into specific steps.

preRoutingHandler

Called before routing, after parsing the request. Can be used for logging, metrics, or overriding routing behavior.

api.register("preRoutingHandler", (c, req, res) => {
console.log("Request received", req.method, req.url);
});

postRoutingHandler

Called after routing, regardless of match success. Useful for metrics or auditing.

api.register("postRoutingHandler", (c, req, res) => {
console.log("Matched operation:", c.operation?.operationId);
});

postSecurityHandler

Called after all security handlers have run.

api.register("postSecurityHandler", (c, req, res) => {
if (!c.security.authorized) console.warn("Unauthorized access attempt");
});

preOperationHandler

Called right before the operation handler. Can be used for setting response headers, request mutation, etc.

api.register("preOperationHandler", (c, req, res) => {
res.setHeader("x-trace-id", generateTraceId());
});

postResponseHandler

Called after the main operation handler. You can use this to validate responses or mutate them.

api.register("postResponseHandler", (c, req, res) => {
const result = c.api.validateResponse(c.response, c.operation);
if (result.errors) {
return res
.status(500)
.json({ error: "Invalid response", details: result.errors });
}
return res.send(c.response);
});

Error Handlers

notFound

Called if the path doesn't match any operation.

api.register("notFound", (c, req, res) => {
res.status(404).json({ error: "Route not found" });
});

methodNotAllowed

Called if the path matches but the method doesn't.

api.register("methodNotAllowed", (c, req, res) => {
res.status(405).json({ error: "Method not allowed" });
});

notImplemented

Called if the operation is matched but no handler is registered.

api.register("notImplemented", (c, req, res) => {
res.status(501).json({ error: "Not implemented" });
});

unauthorizedHandler

Called if the request does not satisfy OpenAPI security requirements.

api.register("unauthorizedHandler", (c, req, res) => {
res.status(401).json({ error: "Unauthorized" });
});

validationFail

Called if the request validation fails.

api.register("validationFail", (c, req, res) => {
res
.status(400)
.json({ error: "Validation failed", details: c.validation.errors });
});