Express OpenAPI Framework

Common errors

• SyntaxError: Invalid regular expression: /^\/v2\/users\((?: ...

  cause An incompatibility between a newer version of the `glob` dependency and `express-openapi`'s path parsing logic, particularly with nested route directory names.
  fix Add `"resolutions": { "glob": "7.x.x" }` (for Yarn) or `"overrides": { "glob": "7.x.x" }` (for npm) to your `package.json` to force an older, compatible version of `glob`.

• HTTP 400 Bad Request or validation errors on API calls.

  cause The incoming request body, parameters, or headers do not conform to the rules defined in your OpenAPI specification (`apiDoc`) for the requested endpoint.
  fix Review the exact validation error messages (often available in the response body or server logs). Adjust the client request to match the API's OpenAPI definition, or update the `apiDoc` if the specification is incorrect.

• Cannot GET /api-docs (or other configured Swagger UI path)

  cause Swagger UI is not correctly initialized, the `docsPath` in `express-openapi.initialize` does not match the path used to serve Swagger UI, or the `apiDoc` is invalid or missing required `info` fields.
  fix Ensure `initialize({ ..., docsPath: '/your-docs-path' })` matches `app.use('/your-docs-path', swaggerUi.serve, swaggerUi.setup(apiDoc));`. Verify `apiDoc` is a valid OpenAPI document with at least `info` and `openapi` fields.

Warnings

• breaking Express.js 5 introduces significant changes to path matching via `path-to-regexp` (v8.x vs v0.x), which `express-openapi` relies on. Migrating an Express 4 application to Express 5 might cause unexpected routing behavior or `SyntaxError: Invalid regular expression` if path patterns are not updated.
  Fix: Review Express 5 migration guides, especially for route definitions and regular expressions. Test thoroughly after upgrading Express. Ensure `path-to-regexp` is compatible or consider pinning its version if issues arise.
• gotcha When using `express-openapi` with nested routes or complex file structures, an older version of the `glob` dependency (prior to v8) can cause `SyntaxError: Invalid regular expression` errors during initialization due to changes in how `glob` handles paths.
  Fix: If encountering `SyntaxError: Invalid regular expression` related to route paths, explicitly pin the `glob` dependency to version `7.x.x` in your `package.json` using `resolutions` (for Yarn) or `overrides` (for npm) to force an older, compatible version of `glob`.
• breaking Upgrading your OpenAPI specification from 2.0 to 3.0, or from 3.0 to 3.1 (when supported by `express-openapi`), can introduce breaking changes to your API contract. `express-openapi` itself supports both 2.0 and 3.0, but changes in your API definition (e.g., parameter locations, schema structure, nullable types in 3.1) can break existing clients.
  Fix: Always use an OpenAPI diff tool (e.g., `openapi-changes`, `spectral diff`) to compare your old and new API definitions before deploying. Communicate breaking changes to API consumers and provide migration guides. Ensure your client-side code is compatible with the new specification.
• gotcha Configuration of middleware (e.g., coercion, validation, defaults) can be done via vendor extensions like `x-express-openapi-disable-middleware`, `x-express-openapi-additional-middleware`. While powerful, these extensions are specific to `express-openapi` and their behavior or availability might evolve across major versions, potentially requiring adjustments to your `apiDoc` configuration.
  Fix: Refer to the `express-openapi` documentation for the specific version you are using to confirm the current behavior and supported vendor extensions for middleware configuration. Test your middleware chain thoroughly after any updates.

Install

• npm install express-openapi npm
• yarn add express-openapi yarn
• pnpm add express-openapi pnpm

Imports

• initialize
  wrong:

  const openapi = require('express-openapi');
  const initialize = openapi.initialize;

  correct:

  import { initialize } from 'express-openapi';

  The primary function to initialize the OpenAPI framework with your Express app. Prefer ES Modules import style.
• OpenApiApp

  import type { OpenApiApp } from 'express-openapi';

  Type import for the initialized OpenAPI application instance, useful for TypeScript projects.

Quickstart

Sets up an Express server, initializes `express-openapi` with an in-memory OpenAPI 3.0 specification, defines a simple '/hello' endpoint, and serves Swagger UI for API exploration. This demonstrates basic setup, routing, and documentation generation.

import express from 'express';
import { initialize } from 'express-openapi';
import * as swaggerUi from 'swagger-ui-express';

const app = express();
const PORT = process.env.PORT ?? 3000;

// Basic API Document - OpenAPI 3.0
const apiDoc = {
  openapi: '3.0.0',
  info: {
    title: 'My Simple API',
    version: '1.0.0',
    description: 'A simple API with Express and OpenAPI'
  },
  paths: {
    '/hello': {
      get: {
        summary: 'Responds with a greeting',
        responses: {
          '200': {
            description: 'Successful response',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    message: { type: 'string' }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
};

// Create a dummy 'operations' object for the path handler
const operations = {
  get: (req: express.Request, res: express.Response) => {
    res.status(200).json({ message: 'Hello, OpenAPI!' });
  }
};

initialize({
  app,
  apiDoc,
  paths: [
    {
      path: '/hello',
      module: operations
    }
  ],
  docsPath: '/api-docs' // Path where Swagger UI will be served
});

// Serve Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(apiDoc as swaggerUi.JsonObject));

// Start the Express server
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
  console.log(`Swagger UI available at http://localhost:${PORT}/api-docs`);
  console.log(`API endpoint at http://localhost:${PORT}/hello`);
});