Swagger Express Validator

Forked off of https://github.com/gargol/swagger-express-validator

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:

1const util = require('util');
2const express = require('express');
3const bodyParser = require('body-parser');
4const validator = require('swagger-express-validator');
5const schema = require('./api-schema.json');
6
7const server = express();
8server.use(bodyParser.json());
9
10const opts = {
11  schema,
12  validateRequest: true,
13  validateResponse: true,
14  nonExistentProperties: true,
15  disallowEmptyStrings: true,
16  requestValidationFn: (req, data, errors) => {
17    console.log(`failed request validation: ${req.method} ${req.originalUrl}\n ${util.inspect(errors)}`)
18  },
19  responseValidationFn: (req, data, errors) => {
20    console.log(`failed response validation: ${req.method} ${req.originalUrl}\n ${util.inspect(errors)}`)
21  },
22};
23server.use(validator(opts));
24
25server.use('/status', (req, res) => {
26  res.json({
27    status: 'OK',
28  })
29});
30server.use((err, req, res, next) => {
31  res.status(500);
32  res.json(err);
33});
34
35return server.listen(3000);
36

Options

• validateRequest
  • Validate the request. Defaults to true
• validateResponse
  • Validate the response. Defaults to true
• allowNullable
  • Allow nullable values. Deafults to 'true'
• nonExistentProperties
  • Do not allow properties not defined in the schema. Defaults to true
• disallowEmptyStrings
  • Do not allow strings to be empty. Defaults to true

Formats

Below is a list of formats that can be validated against request body parameters

• int32 - Is an integer
• int64 - Is an integer
• url - Is a URL
• byte - Is base64
• float - Is a float
• double - Is a float
• email - Is an email
• date - Is a date
• date-time - Is a date
• uuid - Is a UUID
• ipv4 - Is an IP address
• ipv6 - Is an IP address
• numeric - Is numeric
• alphanumeric - Is alphanumeric
• lowercase - Is lowercase
• uppercase - Is uppercase
• macAddress - Is a MAC address
• hex - Is hexadecimal
• md5 - Is MD5
• json - Is JSON
• currency - Is a currency format
• base64 - Is base64

Debugging

To see debug output use DEBUG=swagger-express-validator as an environmental varialbe 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

• Nazar Gargol
• Isaac Stefanek

Licence

MIT

Special thanks to @bgaluszka for initial inspiration :)