OpenAPI 3.x Express Middleware

Common errors

• Error: No handler found for operationId 'myOperation' for '/my-path'

  cause The `operationId` specified in your OpenAPI document does not correspond to an exported function in the designated controller module, or the `x-exegesis-controller` path is incorrect, or `options.controllers` is misconfigured.
  fix Verify that `options.controllers` in your middleware setup points to the correct directory. Confirm that the controller file exists and exports a function with the exact `operationId` name (e.g., `export function myOperation(...)`). Check the `x-exegesis-controller` value in your OpenAPI definition matches the controller file name (without extension).

• TypeError: Cannot read properties of undefined (reading 'query')

  cause This often occurs within a controller function trying to access `context.params.query` or `context.params.path` when a parameter expected is missing or has an incorrect `in` location (e.g., expecting `query` but parameter is `path`).
  fix Review your OpenAPI specification to ensure that parameters are correctly defined with their `in` property (e.g., `in: 'query'`, `in: 'path'`) and that your controller code correctly accesses them (e.g., `context.params.query.myParam`). Add `required: true` to OpenAPI parameters if they are mandatory.

• Response validation error: ... must be string (or similar AJV error)

  cause The data returned by your controller function does not conform to the `response` schema defined in your OpenAPI document for that operation, or the `onResponseValidationError` option is firing.
  fix Compare the data structure and types returned by your controller's operation function against the OpenAPI response schema (`paths['/your-path'].get.responses['200'].content['application/json'].schema`). Adjust either your controller's return value or the OpenAPI schema to match. If `onResponseValidationError` is set, its callback will be invoked.

Warnings

• breaking Version 4.0.0 dropped support for Node.js 10. Users on older Node.js versions must remain on v3.x or upgrade their Node.js environment.
  Fix: Upgrade your Node.js version to 12.x or later. For continued Node.js 10 support, pin `exegesis-express` to a version prior to 4.0.0.
• breaking Version 3.0.0 upgraded the underlying `ajv` library to 8.3.0, which may result in changes to validation error messages. This can affect automated tests or client-side error handling that relies on specific error string matching.
  Fix: Review any code that parses or displays validation error messages to ensure compatibility with the new `ajv` messages. Update tests as necessary.
• breaking Version 2.0.0 dropped support for Node.js 6. Applications running on Node.js 6 must not upgrade to v2.0.0 or higher.
  Fix: Upgrade your Node.js version to 8.x or later. For continued Node.js 6 support, pin `exegesis-express` to a version prior to 2.0.0.
• gotcha `exegesis-express` should generally be placed high in your Express middleware stack, *before* any other body-parsing middlewares (like `express.json()` or `body-parser`). This allows `exegesis` to handle request body parsing according to the OpenAPI specification.
  Fix: Ensure `app.use(exegesisMiddleware)` is called before `app.use(express.json())` or similar body parsers. If a body parser runs first, `exegesis-express` will attempt to use `req.body` if it exists.
• gotcha OpenAPI paths intended to be handled by `exegesis-express` must define the `x-exegesis-controller` extension and `operationId` on each operation. Without these, `exegesis` cannot map incoming requests to the correct controller functions.
  Fix: Add `x-exegesis-controller: 'YourControllerName'` and `operationId: 'yourOperationFunction'` to your OpenAPI path operations, and ensure `options.controllers` points to the directory containing `YourControllerName.js` (or `.ts`).

Install

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

Imports

• middleware
  wrong:

  const { middleware } = require('exegesis-express');

  correct:

  import { middleware } from 'exegesis-express';

  Since v4.0.0, Node.js 10+ is required. Modern projects should prefer ESM imports. CommonJS `require` is still supported but less idiomatic for new code.
• ExegesisOptions

  import type { ExegesisOptions } from 'exegesis-express';

  For TypeScript projects, import types explicitly for `middleware` options for better type checking and IntelliSense.
• OpenApiDocument

  import type { OpenApiDocument } from 'exegesis-express';

  For TypeScript projects, import the `OpenApiDocument` type when working with OpenAPI specifications in JSON/YAML format programmatically.

Quickstart

This quickstart sets up an Express server using `exegesis-express` to serve a simple OpenAPI 3.x defined API. It demonstrates how to initialize the middleware with an OpenAPI specification (inline JSON for simplicity), configure controllers, handle response validation errors, and correctly place the middleware within the Express stack.

import express from 'express';
import { middleware } from 'exegesis-express';
import path from 'path';

const openApiDoc = {
  openapi: '3.0.3',
  info: {
    title: 'Example API',
    version: '1.0.0',
  },
  paths: {
    '/greet': {
      get: {
        'x-exegesis-controller': 'GreetingController',
        operationId: 'greetUser',
        parameters: [
          {
            name: 'name',
            in: 'query',
            schema: { type: 'string', default: 'World' },
            required: false,
          },
        ],
        responses: {
          '200': {
            description: 'A greeting message.',
            content: {
              'application/json': {
                schema: { type: 'object', properties: { message: { type: 'string' } } },
              },
            },
          },
        },
      },
    },
  },
};

// Create a simple controller file (e.g., controllers/GreetingController.ts)
// export function greetUser(context) {
//   const name = context.params.query.name || 'World';
//   return { message: `Hello, ${name}!` };
// }

async function createServer() {
  const app = express();

  const exegesisMiddleware = await middleware(openApiDoc, {
    controllers: path.resolve(__dirname, 'controllers'),
    allowMissingControllers: false,
    onResponseValidationError: (error) => {
      console.error('Response validation error:', error);
    },
  });

  // Exegesis-express should be placed before any body parsers if you want
  // it to handle request body parsing itself.
  app.use(exegesisMiddleware);

  // Catch-all for routes not handled by Exegesis (e.g., 404)
  app.use((req, res) => {
    res.status(404).json({ message: 'Not Found' });
  });

  // Global error handler
  app.use((err, req, res, next) => {
    console.error('Unhandled error:', err);
    res.status(500).json({ message: `Internal server error: ${err.message}` });
  });

  app.listen(3000, () => {
    console.log('Server listening on http://localhost:3000');
    console.log('Try: curl http://localhost:3000/greet?name=Alice');
  });
}

createServer().catch(console.error);