API Reference

Welcome to the express-zod-router API Reference.

This section documents the public APIs, configuration options, types, and behaviors provided by express-zod-router.

Use this section when you need detailed information about a specific API.

TIP

If you're new to express-zod-router, start with the Get Started Guide before exploring the API Reference.

API Overview

express-zod-router provides a small, focused API for building type-safe Express applications with Zod validation and OpenAPI documentation.

The main API areas are:

Router

Create, configure, group, and mount your API routes.

• Router API
• Routes API

Schemas & Validation

Define request and response contracts using Zod schemas.

• Schema API
• Request Validation
• Response Validation

Middleware

Configure middleware at different levels of your API.

• Middleware API

API Versioning

Build and manage versioned API routes.

• Versioning API

OpenAPI

Configure OpenAPI generation and API documentation.

• OpenAPI API

Security

Configure API security and OpenAPI security schemes.

• Security API

Errors

Understand validation errors and API error handling.

• Errors API

Quick Navigation

API	Purpose
Router	Create and configure the main API router
Routes	Register HTTP routes
Schema	Define and use Zod schemas
Request Validation	Validate request data
Responses	Define and validate responses
Middleware	Configure API middleware
Versioning	Configure API versions
OpenAPI	Configure OpenAPI documentation
Security	Configure security schemes
Errors	Handle API and validation errors

Core API

The core API starts with createApiRouter().

import { createApiRouter } from 'express-zod-router';

const api = createApiRouter({
  prefix: '/api',
});

From the API router you can:

createApiRouter()
      │
      ├── HTTP Routes
      │
      ├── Route Modules
      │
      ├── Middleware
      │
      ├── Scoped Routers
      │
      ├── API Versioning
      │
      ├── OpenAPI
      │
      └── Mounting

See the Router API for the complete API.

Route Definition

Routes are defined using a contract-oriented API:

api.get('/users/:id', {
  params: UserParamsSchema,
  response: UserSchema,

  handler: async (req) => {
    return getUser(req.params.id);
  },
});

A route can define:

• Request parameters
• Query parameters
• Request body
• Response schema
• Middleware
• Version information
• OpenAPI metadata
• Route handler

See the Routes API for detailed route options.

Schema API

Zod schemas are used to define runtime contracts.

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
});

Schemas can be used for:

• Request validation
• Response validation
• Type inference
• OpenAPI generation

WARNING

express-zod-router does not provide an api.schema() registration method.

Define schemas using Zod and pass them directly to route options.

For example:

api.post('/users', {
  body: CreateUserSchema,
  response: UserSchema,

  handler: async (req) => {
    return createUser(req.body);
  },
});

See the Schema API for more information.

OpenAPI

OpenAPI documentation is generated from your route definitions and schemas.

api.docs({
  path: '/docs',
  jsonPath: '/openapi.json',

  info: {
    title: 'My API',
    version: '1.0.0',
  },
});

OpenAPI-related configuration includes:

• API documentation
• OpenAPI metadata
• Operation IDs
• Schema names
• Security schemes
• Tags

See the OpenAPI API for detailed configuration.

Middleware

Middleware can be applied at different levels.

api.use(requestLogger);

Or:

const users = api.createRouter({
  path: '/users',
  middleware: [authMiddleware],
});

Middleware can be used for concerns such as:

• Authentication
• Authorization
• Logging
• Request context
• Rate limiting
• Custom request processing

See the Middleware API.

Versioning

API versioning allows different versions of an API to coexist.

const v1 = api.version('v1');

v1.get('/users', {
  handler: async () => {
    return getUsersV1();
  },
});

Versioning can be configured globally and overridden at the router or route level.

See the Versioning API.

API Stability

The API Reference documents the currently implemented public API.

WARNING

Do not assume APIs mentioned in roadmap discussions, GitHub issues, or future plans are currently available.

Only APIs documented as part of the current API Reference should be considered supported public APIs.

Future APIs may change before implementation and release.