Skip to content

OpenAPI ​

express-zod-router generates OpenAPI documentation from route definitions, Zod schemas, and route metadata.

Export your API and list routes ​

Use these methods to share your API with a frontend team, save its documentation during a build, or check which routes are registered. You do not need to start a server.

After registering your routes, call:

ts
api.docs({ info: { title: 'Users API', version: '1.0.0' } });

const document = api.openapi.generate(); // OpenAPI document as an object
const json = api.openapi.toJSON();       // The same document as formatted JSON
const routes = api.inspect();            // Registered routes and their details

generate() uses the same settings as Swagger, including schemas, tags, versions, and security. toJSON() makes it easy to save that document or pass it to a client generator. inspect() lists each route's method, full path, operation ID, and any tags, version, or security settings. It does not include handler code or schemas.

To show only the fields you need, pass fields. TypeScript checks the field names and includes only those fields in the result type. Calling inspect() without options returns all available metadata. Missing optional fields are omitted; fields: [] returns an empty object for each route.

ts
console.table(api.inspect({ fields: ['method', 'path', 'operationId'] }));

To save a file from a build script, import your configured router and write its JSON:

ts
import { writeFile } from 'node:fs/promises';
import { api } from '../src/api';

writeFile('./openapi.json', api.openapi.toJSON()).catch(console.error);

Keep server startup separate from the module you import. These methods do not run your handlers or start Express. Calling api.docs() sets documentation options; it only adds documentation endpoints when you later call api.mount(app).

Each call reads the current routes and returns a separate copy. Changing that copy does not change your API. Register all routes before mounting, since the Swagger document is saved at mount time. Exporting a document does not fully validate it; YAML export and document validation are not included yet.

See the working example. TypeScript users can import OpenApiDocument, OpenApiTooling, and RouteInspection for the results.

Quick example ​

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

const app = express();

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

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

api.get('/users', {
  summary: 'List users',
  description: 'Returns all users.',
  tags: ['Users'],
  response: z.array(UserSchema),

  handler: async () => {
    return [];
  },
});

api.docs({
  path: '/docs',
  jsonPath: '/openapi.json',
  info: {
    title: 'Users API',
    version: '1.0.0',
  },
});

api.mount(app);

The generated documentation is available at:

text
GET /docs
GET /openapi.json

api.docs() ​

Configures OpenAPI documentation and Swagger UI.

ts
api.docs({
  path: '/docs',
  jsonPath: '/openapi.json',
});

Options ​

OptionTypeDescription
pathstringURL path where Swagger UI is served.
jsonPathstringURL path where the OpenAPI JSON document is served.
redocbooleanServe Redoc at /redoc.
scalarbooleanServe Scalar at /scalar.
infoApiDocsInfoOpenAPI API information.
serversApiDocsServer[]OpenAPI server definitions.
openapiRecord<string, unknown>Additional OpenAPI configuration.
swaggerobjectSwagger UI configuration.

Show the JSON URL in Swagger UI ​

Set jsonPath and enable explorer to show Swagger UI's source field. It loads the same JSON endpoint that clients and code generators can use.

ts
api.docs({
  path: '/docs',
  jsonPath: '/openapi.json',
  swagger: {
    explorer: true,
  },
});

Open /docs to view Swagger UI and /openapi.json to open the JSON document directly.

Enable Redoc or Scalar ​

Enable either documentation UI with one option. Both pages load the same OpenAPI JSON document.

ts
api.docs({
  jsonPath: '/openapi.json',
  redoc: true,
  scalar: true,
});

Redoc is served at /redoc and Scalar is served at /scalar. The package uses pinned CDN scripts for these pages. For custom themes, CSP, offline assets, or another UI, see Use Other Documentation UIs.

API information ​

Configure the OpenAPI document information with info.

ts
api.docs({
  info: {
    title: 'Users API',
    version: '1.0.0',
    description: 'API for managing users.',
  },
});

Additional information can be configured:

ts
api.docs({
  info: {
    title: 'Users API',
    version: '1.0.0',
    description: 'API for managing users.',

    contact: {
      name: 'API Support',
      url: 'https://example.com/support',
      email: 'support@example.com',
    },

    license: {
      name: 'MIT',
      url: 'https://opensource.org/licenses/MIT',
    },
  },
});

Servers ​

Configure the servers included in the generated OpenAPI document.

ts
api.docs({
  servers: [
    {
      url: 'https://api.example.com',
      description: 'Production',
    },
    {
      url: 'https://staging.example.com',
      description: 'Staging',
    },
  ],
});

Server variables are also supported:

ts
api.docs({
  servers: [
    {
      url: 'https://{environment}.example.com',
      description: 'Environment server',

      variables: {
        environment: {
          default: 'api',
          enum: ['api', 'staging'],
        },
      },
    },
  ],
});

Route metadata ​

Route metadata is included in the generated OpenAPI document.

ts
api.get('/users/:id', {
  operationId: 'getUser',
  summary: 'Get a user',
  description: 'Returns a user by ID.',
  tags: ['Users'],

  params: z.object({
    id: z.string(),
  }),

  response: UserSchema,

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

Supported route metadata includes:

  • operationId
  • summary
  • description
  • tags
  • deprecated
  • security
  • version
  • openapi

See the Routes API for the complete route configuration.

Operation IDs ​

Configure operation ID generation when creating the API router.

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

Supported strategies are:

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

An operation ID can also be explicitly defined on a route:

ts
api.get('/users', {
  operationId: 'listUsers',

  handler: async () => {
    return [];
  },
});

With strategy: 'explicit', every route must provide operationId. TypeScript reports missing IDs during development, and runtime validation remains as a fallback.

The REST strategy includes the resolved version for versioned routes. For example, GET /v1/users generates listV1Users, while an unversioned GET /users remains listUsers. Explicit operation IDs are unchanged.

Request schemas ​

Zod schemas defined on routes are converted into OpenAPI request schemas.

Body ​

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

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

Parameters ​

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

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

Query ​

ts
api.get('/users', {
  query: UserQuerySchema,

  handler: async (req) => {
    return listUsers(req.query);
  },
});

Response schemas ​

Response schemas are included in the generated OpenAPI responses.

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

  handler: async () => {
    return user;
  },
});

Multiple response statuses can be documented with responses.

ts
api.get('/users/:id', {
  responses: {
    200: {
      schema: UserSchema,
      description: 'User found',
    },

    404: {
      description: 'User not found',
    },
  },

  handler: async () => {
    return user;
  },
});

Request examples ​

Use bodyExample to provide an example request body.

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

  bodyExample: {
    name: 'Om',
    email: 'om@example.com',
  },

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

Response examples ​

Response examples can be configured through the response configuration.

ts
api.get('/users/:id', {
  response: {
    schema: UserSchema,
    example: {
      id: '123',
      name: 'Om',
      email: 'om@example.com',
    },
  },

  handler: async () => {
    return user;
  },
});

Security ​

Security requirements can be included in OpenAPI documentation.

ts
const api = createApiRouter({
  securitySchemes: {
    bearerAuth: {
      type: 'http',
      scheme: 'bearer',
      bearerFormat: 'JWT',
    },
  },
});

Apply a security scheme to a route:

ts
api.get('/profile', {
  security: ['bearerAuth'],

  handler: async () => {
    return profile;
  },
});

See the Security API for more information.

Swagger UI ​

Swagger UI is configured through the swagger option.

ts
api.docs({
  path: '/docs',

  swagger: {
    explorer: true,
    customSiteTitle: 'Users API',
    customCss: `
      .swagger-ui .topbar {
        display: none;
      }
    `,
  },
});

Supported Swagger UI configuration includes:

  • explorer
  • customCss
  • customSiteTitle
  • customfavIcon
  • options

Additional OpenAPI configuration ​

Additional OpenAPI configuration can be provided through the openapi option.

ts
api.docs({
  openapi: {
    openapi: '3.0.3',
  },
});

OpenAPI registry ​

The router exposes its underlying OpenAPI registry through api.registry.

ts
const registry = api.registry;

The registry is provided by @asteasolutions/zod-to-openapi.

This is intended for advanced integrations with the underlying OpenAPI tooling.

OpenAPI generation ​

OpenAPI information is collected from registered routes and their schemas.

text
Route definition
      ↓
Zod schemas + route metadata
      ↓
OpenAPI registry
      ↓
OpenAPI document
      ↓
Swagger UI / JSON endpoint

Example ​

See the complete working OpenAPI example:

Summary ​

  • Use api.docs() to configure OpenAPI documentation.
  • Use info to configure API metadata.
  • Use servers to configure OpenAPI servers.
  • Use route metadata to customize generated documentation.
  • Use Zod schemas for request and response documentation.
  • Use operationId to control OpenAPI operation IDs.
  • Use security and securitySchemes for OpenAPI security requirements.
  • Use swagger to customize Swagger UI.
  • Use api.registry for advanced OpenAPI integrations.

Happy Coding! 🚀