Loading, parsing and validating requests to HTTP services based on Swagger v2.0 documents.
- Fast. Pre-compiled regular expressions and code generation used to validate the inputs and outputs of Swagger 2.0 operations at run-time.
- Typed. swagger2 is implemented in TypeScript 2, including a fully annotated TypeScript definition of the Swagger 2.0 document object. Makes working with Swagger objects more pleasant in the IDE of your choosing (WebStorm, Atom, etc).
$ npm install swagger2 --save
Basic loading and validation of swagger 2.0 document:
import * as swagger from 'swagger2';
// load YAML swagger file
const document = swagger.loadDocumentSync('./swagger.yml');
// validate document
if (!swagger.validateDocument(document)) {
throw Error(`./swagger.yml does not conform to the Swagger 2.0 schema`);
}
You can compile the document for fast validation of operation requests and responses within the framework of your choosing. Koa 2 example:
let app = new Koa();
...
app.use(body());
app.use(createKoaMiddleware(document));
...
function createKoaMiddleware(document: swagger.Document) {
// construct a validation object, pre-compiling all schema and regex required
let compiled = swagger.compileDocument(document);
return async(context, next) => {
if (!context.path.startsWith(document.basePath)) {
// not a path that we care about
await next();
return;
}
let compiledPath = compiled(context.path);
if (compiledPath === undefined) {
// if there is no single matching path, return 404 (not found)
context.status = 404;
return;
}
// check the request matches the swagger schema
let validationErrors = swagger.validateRequest(compiledPath,
context.method, context.request.query, context.request.body);
if (validationErrors === undefined) {
// operation not defined, return 405 (method not allowed)
context.status = 405;
return;
}
if (validationErrors.length > 0) {
context.status = 400;
context.body = {
code: 'SWAGGER_REQUEST_VALIDATION_FAILED',
errors: validationErrors
};
return;
}
// wait for the operation to execute
await next();
// check the response matches the swagger schema
let error = swagger.validateResponse(compiledPath, context.method, context.status, context.body);
if (error) {
error.where = 'response';
context.status = 500;
context.body = {
code: 'SWAGGER_RESPONSE_VALIDATION_FAILED',
errors: [error]
};
}
};
}
There is a complete implementation of this example/use-case in the swagger2-koa module, so if you're using Koa 2 it may make sense to use that instead of swagger2 directly.
- currently only supports synchronous loading of full documents (via swagger.loadDocumentSync)
- does not support validation of header fields
- does not support validation of file attachments
- does not support validation of mime-types
- requires node v6.0 or above
First, grab the source from GitHub.
From within the swagger2 directory, to run tests:
$ npm install
$ npm test
To see code coverage in a web-browser:
$ npm run cover:browser
To clean up:
$ npm run clean
MIT