express-oas-validator

Express OpenAPI Specification (OAS) middleware validator and response validator.

This package will expose an express middleware that will validate your endpoint based on your OpenAPI docs, and a response validator to do the same with your responses payload.

Installation

Install using the node package registry:

npm install --save express-oas-validator

Usage

This is a basic usage of this package.

const express = require('express');
// We recommed to install "body-parser" to validate request body
const bodyParser = require('body-parser');
const { init } = require('express-oas-validator');
const swaggerDefinition = require('./swaggerDefinition.json');

const app = express();

// Each instance of the validator will provide two methods to perform validation
const { validateRequest, validateResponse } = init(swaggerDefinition);

app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());

// Middleware validator
app.post('/api/v1/songs', validateRequest(), (req, res) => res.send('You save a song!'));

// Middleware validator with custom configuration
app.get('/api/v1/albums/:id', validateRequest({ headers: false }), (req, res) => (
  res.json([{
    title: 'abum 1',
  }])
));

// Middleware validator with custom configuration
app.get('/api/v1/authors', validateRequest({ body: false, query: false }), (req, res) => (
  res.json([{
    title: 'abum 1',
  }])
));

// Response validator
app.post('/api/v1/name', (req, res, next) => {
  try {
    validateResponse('Error string', req, 200);
    return res.send('Hello World!');
  } catch (error) {
    return next(error);
  }
});

// Express default error handler
app.use((err, req, res, next) => {
  res.status(err.status).json(err);
});

Methods

init(openApiDef, options)

This method generates a new instance of the validator, which will provide us with the validateRequest and validateResponse methods that we can use to validate the input and output of our endpoints.

It's possible to generate multiple instances using different API definitions and / or configuration.

Parameters

Name	Type	Description
openApiDef	object	OpenAPI definition
options	object	Options to extend the errorHandler or Ajv configuration

Example

const swaggerDefinition = require('./swaggerDefinition.json');

// Each instance of the validator will provide two methods to perform validation
const { validateRequest, validateResponse } = init(swaggerDefinition);

validateRequest(config)

Express middleware that validates the input of the endpoint based on its definition. This includes the request body, headers, path params and query params.

Optionally, the method can receive a parameter with a configuration object to override the defaults and determine which of these inputs we want the middleware to validate.

Parameters

Name	Type	Description
config	object	Options to override the default configuration

Configuration options

Name	Type	Description	Default value
body	boolean	Indicates if request body will be validated	true
params	boolean	Indicates if path params will be validated	true
headers	boolean	Indicates if request headers will be validated	true
query	boolean	Indicates if query params will be validated	true
required	boolean	Indicates if required fields will be validated	true
errorStatusCode	number	HTTP code that will be returned in case the input validation fails	400

Example

// Use middleware with default settings
app.get('/api/v1/albums/:id', validateRequest(), (req, res) => (
  res.json([{
    title: 'abum 1',
  }])
));

// Use middleware with custom settings
app.get('/api/v1/albums/:id', validateRequest({ headers: false }), (req, res) => (
  res.json([{
    title: 'abum 1',
  }])
));

validateResponse(payload, req, status)

Method to validate response payload based on the docs and the status we want to validate.

Parameters

Name	Type	Description
payload	*	Response we want to validate
req	object	Options to extend the errorHandler or Ajv configuration
status	number	Response status we want to validate

Example

validateResponse('Error string', req, 200);

Example with express-jsdoc-swagger

This is an example that uses this library together with express-jsdoc-swagger.

const express = require('express');
const expressJSDocSwagger = require('express-jsdoc-swagger');
const { init } = require('express-oas-validator');

const options = {
  info: {
    version: '1.0.0',
    title: 'Albums store',
    license: {
      name: 'MIT',
    },
  },
  filesPattern: './fake-server.js',
  baseDir: __dirname,
};

const app = express();
const instance = expressJSDocSwagger(app)(options);

const serverApp = () => new Promise(resolve => {
  instance.on('finish', data => {
    const { validateRequest, validateResponse } = init(data);

    /**
     * A song
     * @typedef {object} Song
     * @property {string} title.required - The title
     * @property {string} artist - The artist
     * @property {integer} year - The year
     */

    /**
     * POST /api/v1/songs
     * @param {Song} request.body.required - song info
     * @return {object} 200 - song response
     */
    app.post('/api/v1/songs', validateRequest(), (req, res) => res.send('You save a song!'));

    /**
     * POST /api/v1/name
     * @param {string} request.body.required - name body description
     * @return {object} 200 - song response
     */
    app.post('/api/v1/name', (req, res, next) => {
      try {
        validateResponse('Error string', req);
        return res.send('Hello World!');
      } catch (error) {
        return next(error);
      }
    });

    /**
     * GET /api/v1/authors
     * @summary This is the summary or description of the endpoint
     * @param {string} name.query.required - name param description - enum:type1,type2
     * @param {array<string>} license.query - name param description
     * @return {object} 200 - success response - application/json
     */
    app.get('/api/v1/authors', validateRequest({ headers: false }), (req, res) => (
      res.json([{
        title: 'abum 1',
      }])
    ));

    // eslint-disable-next-line no-unused-vars
    app.use((err, req, res, next) => {
      res.status(err.status).json(err);
    });

    resolve(app);
  });

  app.use(express.urlencoded({ extended: true }));
  app.use(express.json());
});

module.exports = serverApp;