Router API

The router API is the main entry point for creating, configuring, grouping, and mounting express-zod-router routes.

Quick example

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

const app = express();

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

api.get('/health', {
  handler: () => ({
    status: 'ok',
  }),
});

api.mount(app);

createApiRouter(options?)

Creates an API router with its own route registry and OpenAPI configuration.

const api = createApiRouter({
  prefix: '/api',
  middleware: [requestLogger],
});

Options

Option	Type	Description
prefix	string	Prefix prepended to registered routes
middleware	Middleware[]	Global middleware applied to routes
securitySchemes	SecuritySchemes	Registers OpenAPI security schemes
version	VersionConfig	Configures API versioning
openapi	object	Configures OpenAPI operation ID generation

OpenAPI operation ID configuration

const api = createApiRouter({
  openapi: {
    operationId: {
      strategy: 'rest',
    },
  },
});

Supported strategies:

'rest';
'handler';
'explicit';

Mounting

Mount the configured API router on an Express application.

api.mount(app);

Registering route modules

Register reusable route modules with api.routes().

api.routes([usersRoutes, authRoutes]);

A route module can receive the API router and register its routes.

export function usersRoutes(api: ApiRouter) {
  api.get('/users', {
    handler: async () => listUsers(),
  });
}

Global middleware

Add middleware to the API router.

api.use(requestLogger);

Global middleware can also be configured during router creation:

const api = createApiRouter({
  middleware: [requestLogger],
});

Scoped routers

Create a router with a shared path prefix.

const users = api.createRouter('/users');

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

Object configuration can define tags and middleware:

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

Version router

Create a router scoped to a specific API version.

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

v2.get('/users', {
  handler: async () => listUsers(),
});

Example

See the complete working examples:

• examples/basic
• examples/versioning

Summary

• createApiRouter() creates the main API router.
• mount() attaches the API router to Express.
• routes() registers reusable route modules.
• use() adds global middleware.
• createRouter() creates scoped route groups.
• version() creates version-scoped routes.