Miss any of our Open RFC calls?Watch the recordings here! »

swagger-express-validator

1.0.0 • Public • Published

Swagger Express Validator

Build Status

swagger-express-validator is a lightweight middleware for request/response validation based on OpenAPI v2.0 (aka swagger) specification.

The main difference of this package to alternatives like swagger-tools is that this package is very configurable and only concentrates on validation against provided schema. You can choose the behavior of invalid validation like returning a 500 or just logging an error to your logger.

Requirements

  • express ^4.0.0
  • body-parser ^1.0.0

Features

  • Configurable validation behavior
  • Fastest available JSON schema validation based on ajv library
  • Optional validations for either request parameters or response values
  • Independent from express application structure. This is a simple drop-in middleware without additional alterations to your swagger definitions or application routing.
  • Support for nullable field validation though x-nullable attribute

Installation

Start using this library with npm install swagger-express-validator --save

Sample use

To set up simple validation for your requests and responses:

const util = require('util');
const express = require('express');
const bodyParser = require('body-parser');
const validator = require('swagger-express-validator');
const schema = require('./api-schema.json');
 
const server = express();
server.use(bodyParser.json());
 
const opts = {
  schema, // Swagger schema
  preserveResponseContentType: false, // Do not override responses for validation errors to always be JSON, default is true
  returnRequestErrors: true, // Include list of request validation errors with response, default is false
  returnResponseErrors: true, // Include list of response validation errors with response, default is false
  validateRequest: true,
  validateResponse: true,
  requestValidationFn: (req, data, errors) => {
    console.log(`failed request validation: ${req.method} ${req.originalUrl}\n ${util.inspect(errors)}`)
  },
  responseValidationFn: (req, data, errors) => {
    console.log(`failed response validation: ${req.method} ${req.originalUrl}\n ${util.inspect(errors)}`)
  },
};
server.use(validator(opts));
 
server.use('/status', (req, res) => {
  res.json({
    status: 'OK',
  })
});
server.use((err, req, res, next) => {
  res.status(500);
  res.json(err);
});
 
return server.listen(3000);
 

Ajv configuration

swagger-express-validator uses Ajv for schema validation under the hood. You can tweak many validation parameters by passing Ajv configuration overrides:

server.use(validator({
  schema,
  preserveResponseContentType: false,
  returnRequestErrors: true,
  returnResponseErrors: true,
  validateRequest: true,
  validateResponse: true,
  ajvRequestOptions: {
    coerceTypes: true,
  },
  ajvResponseOptions: {
    coerceTypes: true,
  },
}));

See Ajv documentation for supported values.

Debugging

To see debug output use DEBUG=swagger-express-validator as an environmental variable when starting your project, eg.: DEBUG=swagger-express-validator node server.js. To gain more insights on how this works see documentation of debug library

Contributors

Licence

MIT

Special thanks to @bgaluszka for initial inspiration :)

Install

npm i swagger-express-validator

DownloadsWeekly Downloads

571

Version

1.0.0

License

MIT

Unpacked Size

175 kB

Total Files

16

Last publish

Collaborators

  • avatar
  • avatar