Skip to content

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.

Lifecycle hooks for request, response, and error observability are configured through createApiRouter().

Schemas & Validation ​

Define request and response contracts using Zod schemas.

Middleware ​

Configure middleware at different levels of your API.

API Versioning ​

Build and manage versioned API routes.

OpenAPI ​

Configure OpenAPI generation and API documentation.

Security ​

Configure API security and OpenAPI security schemes.

Errors ​

Understand validation errors and API error handling.

Quick Navigation ​

APIPurpose
RouterCreate and configure the main API router
RoutesRegister HTTP routes
SchemaDefine and use Zod schemas
Request ValidationValidate request data
Headers and CookiesValidate request headers and cookies
ResponsesDefine and validate responses
MiddlewareConfigure API middleware
VersioningConfigure API versions
OpenAPIConfigure OpenAPI documentation
SecurityConfigure security schemes
ErrorsHandle API and validation errors

Core API ​

The core API starts with createApiRouter().

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

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

From the API router you can:

text
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:

ts
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
  • Request headers and cookies
  • 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.

ts
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:

ts
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.

ts
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.

ts
api.use(requestLogger);

Or:

ts
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.

ts
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.

Happy Coding! 🚀