express-openapi-validate

0.6.1 verified Sat Apr 25 auth: no javascript maintenance

Express middleware for validating request bodies, query parameters, path parameters, and headers against an OpenAPI 3.0 document. Uses Ajv v8 for JSON Schema draft-04/05 validation as required by OpenAPI 3. Supports automatic request matching via validator.match(), optional allowNoMatch for missing routes, and custom Ajv options. Current stable version 0.6.1, released 2022, with infrequent releases. Key differentiator: simple integration with Express, TypeScript types included, support for discriminator keywords and extra OAS keywords. Alternative: express-openapi-validator.

Common errors

error SyntaxError: Unexpected token in JSON at position 0 ↓

cause Passing a JavaScript object instead of a JSON string to OpenApiValidator constructor.

fix

Ensure the document is an object (already parsed from JSON/YAML). If using JSON.parse/require, it's already an object.

error TypeError: Cannot destructure property 'OpenApiValidator' of ... undefined ↓

cause Using default import instead of named import.

fix

Use: import { OpenApiValidator } from 'express-openapi-validate'

error Error: No matching operation for POST /unknown ↓

cause Validator.match() cannot find a matching route specification. Throw occurs if allowNoMatch is not set.

fix

Either add the operation to your OpenAPI document or use: validator.match({ allowNoMatch: true })

error ValidationError: request.body should have required property 'input' ↓

cause Request body does not match schema defined in OpenAPI document.

fix

Ensure request body includes all required properties as defined in the OpenAPI schema.

Warnings

breaking Ajv upgrade from v6 to v8 in v0.6.0: custom Ajv options may require changes per Ajv migration guide. ↓

fix Review Ajv v8 migration guide (https://ajv.js.org/v6-to-v8-migration.html) for changes in options like $data, formats, keywords.

breaking validator.match() throws error if no matching route spec found in v0.6.0. Use match({ allowNoMatch: true }) for old behavior. ↓

fix Pass allowNoMatch option: app.use(validator.match({ allowNoMatch: true }))

breaking Node 10 support dropped in v0.6.0. ↓

fix Upgrade Node.js to v12 or higher.

breaking JSON Schema draft-04/05 used since v0.4.0 instead of draft-07. Some valid draft-07 schemas may fail. ↓

fix Ensure schemas conform to draft-04/05; avoid draft-07-only features like if/then/else.

deprecated Node 6 and 8 support dropped in v0.5.0. ↓

fix Upgrade Node.js to v10 or higher (v12+ recommended).

Install

npm install express-openapi-validate

yarn add express-openapi-validate

pnpm add express-openapi-validate

Imports

OpenApiValidator
wrong
```
const OpenApiValidator = require('express-openapi-validate')
```
correct
```
import { OpenApiValidator } from 'express-openapi-validate'
```
Default import not supported; must use named import. CommonJS require works with { OpenApiValidator } destructuring.

OpenApiDocument

wrong

import { OpenApiDocument } from 'express-openapi-validate'

correct

import type { OpenApiDocument } from 'express-openapi-validate'

OpenApiDocument is a TypeScript type, only import as type to avoid runtime errors.

validator.validate

wrong

validator.validate('post','/path')(req,res)

correct

import { OpenApiValidator } from 'express-openapi-validate';
const validator = new OpenApiValidator(doc);
router.post('/path', validator.validate('post', '/path'))

validator.validate returns middleware, not invoked directly.

Quickstart

Express server with OpenAPI validation using validator.validate() and custom Ajv options.

const fs = require('fs');
const express = require('express');
const { OpenApiValidator } = require('express-openapi-validate');
const YAML = require('js-yaml');

const app = express();
app.use(express.json());

const apiDoc = YAML.load(fs.readFileSync('./openapi.yaml', 'utf8'));
const validator = new OpenApiValidator(apiDoc, {
  ajvOptions: { coerceTypes: true },
});

app.post('/echo', validator.validate('post', '/echo'), (req, res) => {
  res.json({ output: req.body.input });
});

app.use((err, req, res, next) => {
  res.status(err.statusCode || 500).json({ error: err.message });
});

app.listen(3000);