Operation Handlers
Handlers are controllers for operations described in your OpenAPI document. They are registered for each operationId
found in the OpenAPI definitions.
import type { Context } from "openapi-backend";
import type { Request, Response } from "express";
async function getPetByIdHandler(
c: Context<{ id: string }>,
_req: Request,
res: Response
) {
const id = c.request.params.id;
const pet = await pets.getPetById(id);
return res.status(200).json({ result: pet });
}
api.register("getPetById", getPetByIdHandler);
// or
api.register({
getPetById: getPetByIdHandler,
});
Operation handlers are passed a special Context object as the first argument, which contains the parsed request, the matched API operation and input validation results.
Arguments 2 and higher are passed through from handleRequest
validationFail Handler
The validationFail
handler gets called by .handleRequest()
if the input validation fails for a request.
HINT: You should probably return a 400 status code from this handler.
Example handler:
function validationFailHandler(c, req, res) {
return res.status(400).json({ status: 400, err: c.validation.errors });
}
api.register("validationFail", validationFailHandler);
notFound Handler
The notFound
handler gets called by .handleRequest()
if the path doesn't
match an operation in the API definitions.
HINT: You should probably return a 404 status code from this handler.
Example handler:
function notFound(c, req, res) {
return res.status(404).json({ status: 404, err: "Not found" });
}
api.register("notFound", notFound);
methodNotAllowed Handler
The methodNotAllowed
handler gets called by .handleRequest()
if request
method does not match any operations for the path.
If this handler isn't registered, the notFound Handler will be used instead.
HINT: You should probably return a 405 status code from this handler.
Example handler:
function methodNotAllowed(c, req, res) {
return res.status(405).json({ status: 405, err: "Method not allowed" });
}
api.register("methodNotAllowed", methodNotAllowed);
notImplemented Handler
The notImplemented
handler gets called by .handleRequest()
if no other Operation Handler has been registered for
the matched operation.
HINT: You can either mock the response or return a 501 status code.
Example handler:
function notImplementedHandler(c, req, res) {
return res
.status(404)
.json({ status: 501, err: "No handler registered for operation" });
}
api.register("notImplemented", notImplementedHandler);
unauthorizedHandler Handler
The unauthorizedHandler
handler gets called by .handleRequest()
if security
requirements are not met after checking Security Requirements
and calling their Security Handlers.
HINT: You should probably return a 401 or 403 code from this handler and instruct the client to authenticate.
Example handler:
function unauthorizedHandler(c, req, res) {
return res
.status(401)
.json({ status: 401, err: "Please authenticate first" });
}
api.register("unauthorizedHandler", unauthorizedHandler);
If no unauthorizedHandler
is registered, the Security Handlers will still be
called and their output and the authorization status for the request can be
checked in operation handlers via the context.security
property.
postResponseHandler Handler
The postResponseHandler
handler gets called by .handleRequest()
after resolving the response handler.
The return value of the response handler will be passed in the context object response
property.
HINT: You can use the postResponseHandler to validate API responses against your response schema
Example handler:
function postResponseHandler(c, req, res) {
const valid = c.api.validateResponse(c.response, c.operation);
if (valid.errors) {
// response validation failed
return res.status(502).json({ status: 502, err: valid.errors });
}
return res.status(200).json(c.response);
}
api.register("postResponseHandler", postResponseHandler);