swagger-express-validator
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/swagger-express-validator package

    1.0.2 • 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

    969

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    15.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • gargol
    • kibertoad