Registry / web-framework / exegesis-express

exegesis-express

library4.0.0jsnpmunverified

exegesis-express provides Express middleware for handling OpenAPI 3.x API definitions, acting as a wrapper around the core `exegesis` library. It offers full support for OpenAPI 3.x.x features including request body parsing (JSON, form-urlencoded), response validation, authentication, and extensibility via a plugin system and custom format validation. The current stable version is 4.0.0, released in December 2021. While not on a fixed release cadence, it typically updates in conjunction with its parent `exegesis` library, incorporating bug fixes, security patches, and Node.js version support changes. Key differentiators include comprehensive OpenAPI 3.x conformance, flexible middleware placement, and robust error handling for API-driven applications.

web-framework http-networking auth-security serialization

npm install exegesis-express

github ↗package ↗

INSTALL

IMPORT

SIG · EXEGESIS-EXPRESS

exegesis-express

web-frameworkjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

middleware

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

✗ const { middleware } = require('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.

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);

Debug

Known issues

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

affects: >=4.0.0

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

affects: >=3.0.0

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

affects: >=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.

affects: >=1.0.0

gotchaOpenAPI 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`).

affects: >=1.0.0

Errors

Common errors & fixes

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

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')

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)

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.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

expressrequiredRuntime peer dependency for creating and managing web servers; `exegesis-express` functions as Express middleware.

exegesisrequiredCore library that `exegesis-express` wraps, providing the OpenAPI 3.x parsing, validation, and routing logic.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/exegesis-js/exegesis-express ↗

packagehttps://www.npmjs.com/package/exegesis-express ↗