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:

1npm install --save express-oas-validator

Usage

This is a basic usage of this package.

1const express = require('express');
2// We recommed to install "body-parser" to validate request body
3const bodyParser = require('body-parser');
4const { init } = require('express-oas-validator');
5const swaggerDefinition = require('./swaggerDefinition.json');
6
7const app = express();
8
9// Each instance of the validator will provide two methods to perform validation
10const { validateRequest, validateResponse } = init(swaggerDefinition);
11
12app.use(bodyParser.urlencoded({ extended: true }));
13app.use(bodyParser.json());
14
15// Middleware validator
16app.post('/api/v1/songs', validateRequest(), (req, res) => res.send('You save a song!'));
17
18// Middleware validator with custom configuration
19app.get('/api/v1/albums/:id', validateRequest({ headers: false }), (req, res) => (
20  res.json([{
21    title: 'abum 1',
22  }])
23));
24
25// Middleware validator with custom configuration
26app.get('/api/v1/authors', validateRequest({ body: false, query: false }), (req, res) => (
27  res.json([{
28    title: 'abum 1',
29  }])
30));
31
32// Response validator
33app.post('/api/v1/name', (req, res, next) => {
34  try {
35    validateResponse('Error string', req, 200);
36    return res.send('Hello World!');
37  } catch (error) {
38    return next(error);
39  }
40});
41
42// Express default error handler
43app.use((err, req, res, next) => {
44  res.status(err.status).json(err);
45});

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

1const swaggerDefinition = require('./swaggerDefinition.json');
2
3// Each instance of the validator will provide two methods to perform validation
4const { 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

1// Use middleware with default settings
2app.get('/api/v1/albums/:id', validateRequest(), (req, res) => (
3  res.json([{
4    title: 'abum 1',
5  }])
6));
7
8// Use middleware with custom settings
9app.get('/api/v1/albums/:id', validateRequest({ headers: false }), (req, res) => (
10  res.json([{
11    title: 'abum 1',
12  }])
13));

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

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

Example with express-jsdoc-swagger

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

1const express = require('express');
2const expressJSDocSwagger = require('express-jsdoc-swagger');
3const { init } = require('express-oas-validator');
4
5const options = {
6  info: {
7    version: '1.0.0',
8    title: 'Albums store',
9    license: {
10      name: 'MIT',
11    },
12  },
13  filesPattern: './fake-server.js',
14  baseDir: __dirname,
15};
16
17const app = express();
18const instance = expressJSDocSwagger(app)(options);
19
20const serverApp = () => new Promise(resolve => {
21  instance.on('finish', data => {
22    const { validateRequest, validateResponse } = init(data);
23
24    /**
25     * A song
26     * @typedef {object} Song
27     * @property {string} title.required - The title
28     * @property {string} artist - The artist
29     * @property {integer} year - The year
30     */
31
32    /**
33     * POST /api/v1/songs
34     * @param {Song} request.body.required - song info
35     * @return {object} 200 - song response
36     */
37    app.post('/api/v1/songs', validateRequest(), (req, res) => res.send('You save a song!'));
38
39    /**
40     * POST /api/v1/name
41     * @param {string} request.body.required - name body description
42     * @return {object} 200 - song response
43     */
44    app.post('/api/v1/name', (req, res, next) => {
45      try {
46        validateResponse('Error string', req);
47        return res.send('Hello World!');
48      } catch (error) {
49        return next(error);
50      }
51    });
52
53    /**
54     * GET /api/v1/authors
55     * @summary This is the summary or description of the endpoint
56     * @param {string} name.query.required - name param description - enum:type1,type2
57     * @param {array<string>} license.query - name param description
58     * @return {object} 200 - success response - application/json
59     */
60    app.get('/api/v1/authors', validateRequest({ headers: false }), (req, res) => (
61      res.json([{
62        title: 'abum 1',
63      }])
64    ));
65
66    // eslint-disable-next-line no-unused-vars
67    app.use((err, req, res, next) => {
68      res.status(err.status).json(err);
69    });
70
71    resolve(app);
72  });
73
74  app.use(express.urlencoded({ extended: true }));
75  app.use(express.json());
76});
77
78module.exports = serverApp;