Zooz/express-ajv-swagger-validation


Input validation using Swagger (Open API) and ajv

License: Apache-2.0

Language: JavaScript


express-ajv-swagger-validation

NPM

NPM

Join the chat at https://gitter.im/Zooz/express-ajv-swagger-validation NPM Version NPM Downloads Build Status Test Coverage NSP Status Apache 2.0 License

This package is used to perform input validation to express app using a Swagger (Open API) definition and ajv

Table of Contents

Install

npm install --save express-ajv-swagger-validation

API

How to use

var swaggerValidator = require('express-ajv-swagger-validation');

express-ajv-swagger-validation.validate

This Middleware validate the request body, headers, path parameters and query parameters according to the path definition in the swagger file. Please make sure to use this middleware inside route definition in order to have req.route.path assign to the most accurate express route.

express-ajv-swagger-validation.init(PathToSwaggerFile, options)

Init the middleware with the swagger definition.

The function return Promise.

Arguments

  • PathToSwaggerFile – Path to the swagger definition
  • options – Additional options for the middleware.
Options

Options currently supports:

  • framework - Defines in which framework the middleware is working ('koa' or 'express'). As default, set to 'express'.

  • formats - Array of formats that can be added to ajv configuration, each element in the array should include name and pattern.

  • beautifyErrors- Boolean that indicates if to beautify the errors, in this case it will create a string from the Ajv error.

    • Examples:
      • query/limit should be <= 100 - query param
      • path/petId should NOT be shorter than 3 characters - path param not in format
      • body/[0].test.field1 should be string - Item in an array body
      • body/test should have required property 'field1' - nested field
      • body should have required property 'name' - Missing field in body

    You can see more examples in the tests

  • firstError - Boolean that indicates if to return only the first error.

  • makeOptionalAttributesNullable - Boolean that forces preprocessing of Swagger schema to include 'null' as possible type for all non-required properties. Main use-case for this is to ensure correct handling of null values when Ajv type coercion is enabled

  • ajvConfigBody - Object that will be passed as config to new Ajv instance which will be used for validating request body. Can be useful to e. g. enable type coercion (to automatically convert strings to numbers etc). See Ajv documentation for supported values.

  • ajvConfigParams - Object that will be passed as config to new Ajv instance which will be used for validating request body. See Ajv documentation for supported values.

  • contentTypeValidation - Boolean that indicates if to perform content type validation in case consume field is specified and the request body is not empty.

  • expectFormFieldsInBody - Boolean that indicates whether form fields of non-file type that are specified in the schema should be validated against request body (e. g. Multer is copying text form fields to body)

formats: [
    { name: 'double', pattern: /\d+\.(\d+)+/ },
    { name: 'int64', pattern: /^\d{1,19}$/ },
    { name: 'int32', pattern: /^\d{1,10}$/ }
]

Usage Example

Express

swaggerValidator.init('test/unit-tests/input-validation/pet-store-swagger.yaml')
    .then(function () {
        var app = express();
        app.use(bodyParser.json());
        app.get('/pets', swaggerValidator.validate, function (req, res, next) {
            res.json({ result: 'OK' });
        });
        app.post('/pets', swaggerValidator.validate, function (req, res, next) {
            res.json({ result: 'OK' });
        });
        app.get('/pets/:petId', swaggerValidator.validate, function (req, res, next) {
            res.json({ result: 'OK' });
        });

        app.use(function (err, req, res, next) {
            if (err instanceof swaggerValidator.InputValidationError) {
                res.status(400).json({ more_info: JSON.stringify(err.errors) });
            }
        });

        var server = app.listen(serverPort, function () {
        });
    });

Koa

'use strict';
const Koa = require('koa');
const Router = require('koa-router');
const bodyParser = require('koa-bodyparser');
const inputValidation = require('../../src/middleware');
let app = new Koa();
let router = new Router();
app.use(bodyParser());
app.use(router.routes());
module.exports = inputValidation.init('test/pet-store-swagger.yaml', {framework: 'koa'})
    .then(function () {
        router.get('/pets', inputValidation.validate, async function(ctx, next) {
            ctx.status = 200;
            ctx.body = { result: 'OK' };
        });
        router.post('/pets', inputValidation.validate, async function (ctx, next) {
            ctx.status = 200;
            ctx.body = { result: 'OK' };
        });
        router.get('/pets/:petId', inputValidation.validate, async function (ctx, next) {
            ctx.status = 200;
            ctx.body = { result: 'OK' };
        });
        router.put('/pets', inputValidation.validate, async function (ctx, next) {
            ctx.status = 200;
            ctx.body = { result: 'OK' };
        });

        return Promise.resolve(app);
    });

Important Notes

  • Objects - it is important to set any objects with the property type: object inside your swagger file, although it isn't a must in the Swagger (OpenAPI) spec in order to validate it accurately with ajv it must be marked as object
  • multipart/form-data (files) supports is based on express/multer
  • koa support - When using this package as middleware for koa, the validations errors are being thrown.
  • koa packages - This package supports koa server that uses koa-router, koa-bodyparser and koa-multer

Open api 3 - known issues

  • supporting inheritance with discriminator , only if the ancestor object is the discriminator.
  • The discriminator supports in the inheritance chain stop when getting to a child with no discriminator (a leaf in the inheritance tree), meaning a leaf can't have a field which starts a new inheritance tree. so child with no discriminator cant point to other child with discriminator,

Running Tests

Using mocha, istanbul and mochawesome

npm test

Project Statistics

Sourcerank 5
Repository Size 258 KB
Stars 9
Forks 15
Watchers 5
Open issues 6
Dependencies 369
Contributors 7
Tags 20
Created
Last updated
Last pushed

Top Contributors See all

idanto Igor Savin DY6229 Royvaknin29 ugolas rotemza12 manorlh

Packages Referencing this Repo

express-ajv-swagger-validation
Input validation using Swagger (Open API) and ajv
Latest release 0.8.1 - Updated - 9 stars

Recent Tags See all

v0.8.1 February 18, 2019
v0.8.0 January 31, 2019
v0.7.1 January 29, 2019
v0.7.0 January 24, 2019
v0.6.3 September 13, 2018
v0.6.2 May 09, 2018
v0.6.1 March 10, 2018
v0.6.0 March 10, 2018
v0.5.2 February 27, 2018
v0.5.1 February 22, 2018
v0.5.0 February 22, 2018
v0.4.1 January 23, 2018
v0.4.0 January 03, 2018
v0.3.3 December 28, 2017
v0.3.2 December 27, 2017

Something wrong with this page? Make a suggestion

Last synced: 2019-02-18 13:22:39 UTC

Login to resync this repository