This is a small library that validates HTTP requests and responses against an OpenAPI 3.0 specification.

It is designed to work with any web servers/framework that uses the Fetch API such as:

• Cloudflare Workers
• Astro
• Remix

It also provides adapters for non-Fetch based web servers/frameworks such as:

• AWS Lambda
• Express (coming soon)
• Fastify (coming soon)

The library is built on top of Zod and zod-to-openapi.

• Installation
• Define an OpenAPI route
• Create a validator
• Validate requests and responses
• Error handling
• Adapters
  • AWS Lambda
  • Express
  • Fastify

Installation

1npm install --save @oselvar/openapi-validator

Define an OpenAPI route

1import { RouteConfig } from '@asteasolutions/zod-to-openapi';
2import { z } from 'zod';
3
4import {
5  Response404,
6  Response415,
7  Response422,
8  Response500,
9} from '@oselvar/openapi-validator';
10
11// Define Zod schemas for the request parameters, query and body
12
13const ThingParamsSchema = z.object({
14  thingId: z.string().regex(/[\d]+/),
15});
16
17const ThingQuerySchema = z.object({
18  thingId: z.string().regex(/[\d]+/).optional(),
19});
20
21const ThingBodySchema = z.object({
22  name: z.string().regex(/[a-z]+/),
23  description: z.string().regex(/[a-z]+/),
24});
25
26// Define an OpenAPI route using https://github.com/asteasolutions/zod-to-openapi
27
28const routeConfig: RouteConfig = {
29  method: 'post',
30  path: '/things/{thingId}',
31  request: {
32    params: ThingParamsSchema,
33    query: ThingQuerySchema,
34    body: {
35      content: {
36        'application/json': {
37          schema: ThingBodySchema,
38        },
39      },
40    },
41  },
42  responses: {
43    200: {
44      description: 'Create a thing',
45      content: {
46        'application/json': {
47          schema: ThingBodySchema,
48        },
49      },
50    },
51    404: Response404,
52    415: Response415,
53    422: Response422,
54    500: Response500,
55  },
56};

Create a validator

The Validator class uses the schemas in the routeConfig object to validate requests and responses.

1import { Validator } from '@oselvar/openapi-validator';
2
3const validator = new Validator(routeConfig);

Validate requests and responses

Your web server will provide a request object and a params object.

(If your web server does not use the Fetch API, see the Adapters section below.)

1const request: Request = ...;
2const params: Record<string, string | undefined> = ...;
3
4const params = validator.params<z.infer<typeof ThingParamsSchema>>(params);
5const body = await validator.body<z.infer<typeof ThingBodySchema>>(request);
6const response = validator.validate(Response.json(body));

Error handling

The methods on the Validator object will throw a ValidationError if the request or response is invalid. You must handle this error and return an appropriate HTTP response to the client.

We recommend doing this in a middleware function. Please refer to your web server's documentation for more information.

Here is an example:

1import { unwrapError } from '@oselvar/openapi-validator';
2
3try {
4  // Run the handler
5} catch (error) {
6  const { message, response } = unwrapError(error);
7  console.error(response.status, message);
8  return response;
9}

Adapters

If you are using a framework that does not use the Fetch API Request and Response objects such as AWS Lambda, Express or Fastify, use the FetchRoute type to define your handler function:

1import { FetchRoute, Validator } from '@oselvar/openapi-validator';
2import { RouteConfig } from '@asteasolutions/zod-to-openapi';
3import { z } from 'zod';
4
5const routeConfig: RouteConfig = { ... };
6const validator = new Validator(routeConfig);
7
8const fetchRoute: FetchRoute = async (context) => {
9  const params = validator.params<z.infer<typeof ThingParamsSchema>>(context.params);
10  const body = await validator.body<z.infer<typeof ThingBodySchema>>(context.request);
11  return validator.validate(Response.json(body));
12};

Note that the support for multiple HTTP servers can also simplify your developer experience. You can write your handler function once and then register it with multiple HTTP servers.

For example, you can register your handler functions with Express or Fastify during development and then register them with AWS Lambda during production.

The next step is to convert the FetchRoute to a function that can be registered with your HTTP server.

AWS Lambda

1import { FetchOpenAPIHandler } from '@oselvar/openapi-validator';
2import { toProxyHandler } from '@oselvar/openapi-validator/aws-lambda';
3
4export const handler = toProxyHandler(fetchRoute);

Express

Coming soon.

Fastify

Coming soon.