swagger2

Loading, parsing and validating requests to HTTP services based on Swagger v2.0 documents.

Benefits

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).

Installation

$ npm install swagger2 --save

Usage

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.

Limitations

currently only supports synchronous loading of full documents (via swagger.loadDocumentSync)
does not support validation of file attachments
does not support validation of mime-types
requires node v6.0 or above

Development

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

License

MIT