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, 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 add swagger2

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 v16.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 ci:coverage
$ open coverage/lcov-report/index.html (on Mac)

To clean up:

$ npm run clean

License

MIT