Skip to content

Express OpenAPI Specification (OAS) middleware validator

License

Notifications You must be signed in to change notification settings

BRIKEV/express-oas-validator

Repository files navigation

npm Build Known Vulnerabilities Maintainability Test Coverage License: MIT

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;