swagger-endpoint-validator
A validator of API endpoints to check that input and/or output match with the swagger specification for the API.
This is based on express-swagger-generator, so it is important that each endpoints is properly documented so that the library can do the validation.
Installation
npm install --save swagger-endpoint-validator
Methods
init(app: ExpressApp, validatorOptions: ConfigFile, format: String)
validator.init(app, validatorOptions, format);
where:
app
is the Express app instance.format
is an string to choose the format we want to create the swagger docs: jsdoc
or yaml
. Default jsdoc
.validatorOptions
is a configuration object that has different format depending on format
:
validatorOptions
for jsdoc
const validatorOptions = {
swaggerDefinition: {
info: {
description: 'Documentation for Service API',
title: 'Service API',
version: '1.0.0',
contact: { email: 'your_email@guidesmiths.com' },
},
host: 'localhost:5000',
basePath: '/',
produces: ['application/json'],
schemes: ['http'],
securityDefinitions: {
JWT: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
description: '',
},
},
},
basedir: process.cwd(),
files: ['./test/**/**.js'],
route: {
url: '/test/docs/api',
docs: '/test/docs/api.json',
},
};
validatorOptions
for yaml
const validatorOptions = {
swaggerDefinition: {
info: {
description: 'Documentation for Service API',
title: 'Service API',
version: '1.0.0',
contact: { email: 'your_email@guidesmiths.com' },
},
basePath: '/',
},
apis: ['./test/**/**.js'],
url: '/test/docs/api',
};
validateAPIInput(input: Object, request: RequestObject)
validator.validateAPIInput(input, request);
where:
input
is the payload to be validated.request
is request object.
It will use the configuration used in the initialization to look for the endpoint and the schema to validate.
JSDOC Example
app.get('/test-invalid-input', (req, res) => {
try {
validator.validateAPIInput({}, req);
} catch (error) {
res.status(404).json({ error });
}
});
YAML Example
app.post('/test-invalid-input', (req, res) => {
try {
const result = validator.validateAPIInput({}, req);
res.status(200).json(result);
} catch (error) {
res.status(404).json({ error });
}
});
validateAPIOutput(output: Object, request: RequestObject)
validator.validateAPIOutput(output, request);
where:
output
is the payload to be validated.request
is request object.
It will use the configuration used in the initialization to look for the endpoint and the schema to validate.
JSDOC Example
app.get('/test-invalid-output', (req, res) => {
const validInputModel = { name: 'Name is required' };
try {
validator.validateAPIInput(validInputModel, req);
validator.validateAPIOutput({}, req);
} catch (error) {
res.status(404).json({ error });
}
});
YAML Example
app.get('/test-invalid-output', (req, res) => {
try {
const result = validator.validateAPIOutput({}, req);
res.status(200).json(result);
} catch (error) {
res.status(404).json({ error });
}
});
Example of a valid request with the validator
JSDOC
app.get('/test-valid', (req, res) => {
const validInputModel = { name: 'Name is required' };
const validOutputModel = { name: 'Name is required', result: 'Valid result' };
validator.validateAPIInput(validInputModel, req);
validator.validateAPIOutput(validOutputModel, req);
res.status(200).json({ success: true });
});
YAML
app.post('/test-valid-input', (req, res) => {
const validInputModel = { name: 'Name is required' };
try {
const result = validator.validateAPIInput(validInputModel, req);
res.status(200).json(result);
} catch (error) {
res.status(404).json({ error });
}
});
app.get('/test-valid-output', (req, res) => {
const validInputModel = { name: 'Name is required' };
const validOutputModel = { name: 'Name is required', result: 'Valid result' };
try {
validator.validateAPIInput(validInputModel, req);
const result = validator.validateAPIOutput(validOutputModel, req);
res.status(200).json(result);
} catch (error) {
res.status(404).json({ error });
}
});