swagger-spec-middleware

This is simple middleware for ExpressJS to handle resources given by the Swagger spec file.

##Features

• Easy installation
• Support default handlers comosed with method + path, for example: getPets will handle paths -> '/pets' -> get
• Support named handlers customized by operationId in specification file
• Support get, post, put and delete operation methods
• Parameters are automatically passed to handlers as arguments
• Support query, header, path, formData, body parameter sources
• Parameters are automatically converted to the target type and format
• Handling exceptions, generic, custom and global exceptions customization

##Planned features

• Support parameters default value
• Input parameters validation, support for:
  • required
  • maximum
  • exclusiveMaximum
  • minimum
  • exclusiveMinimum
  • maxLength
  • minLength
  • pattern
  • maxItems
  • minItems
  • uniqueItems
  • enum
  • multipleOf
• Arrays type support
• Collection format support
• Schema validation
• Meta information passing to handler
• Support for consumes and produces; input and output format determined by Accept and Content-Type header fields
• Support inheritance for specification configuration model
• Definitions, Parameters, Responses and References support
• Support other Swagger Spec versions than 2.0
• Add support for lifecycle like turn off validation, preprocessors and afterprocessors for handlers etc.

##Not planned features

• Support for options, head, patch operation methods
• Support security layer
• Support for XML Objects

Hello world

Install it:

npm install --save swagger-spec-middleware

use it next to ExpressJS app:

var express = require('express');
var app = express();
var swaggerSpecMiddleware = require('swagger-spec-middleware');
swaggerSpecMiddleware.host(app, {
    spec: 'spec.json',
    handlers: {
        'petsGet': function (req, resp) {
            resp.send(200);
        }
    }
});

where spec.json:

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Swagger ToyStore"
    },
    "host": "petstore.swagger.wordnik.com",
    "basePath": "/api",
    "schemes": [
        "http"
    ],
    "paths": {
        "/pets": {
            "get": {
                "operationId": "petsGet",
                "responses": {
                    "200": {
                    }
                }
            }
        }
    }
    
}

#Documentation ##Installation

Install dependency in the project by:

npm install --save swagger-spec-middleware

Add to your ExpressJS application and start using it:

var swaggerSpecMiddleware = require('swagger-spec-middleware');
swaggerSpecMiddleware.host(app, {
    spec: 'spec.json',
    handlers: {
        'petsGet': function (req, resp) {
            resp.send(200);
        }
    }
});

where spec.json is Swagger specification file with resources description that needs to be handled.

##Handlers ###Default handlers By default, default handlers are being looking first. When given operation is defined in spec file:

"paths": {
    "/pets": {
        "get": {
            "responses": {
                "200": {
                }
            }
        }
    }
}

then this resource can be handled by the default handler getPets:

'getCars': function (req, resp) {
        resp.send(200);
}

###Named handlers Resource can be explicitly named by operationId in spec operation:

"/pets": {
    "get": {
        "operationId": "petsGet",
        "responses": {
            "200": {
            }
        }
    }
}

then supported handler for this operation is petsGet.

'petsGet': function (req, resp) {
        resp.send(200);
}

OperationId handler overrides default handler. When also getPets handler specified, only petsGet will be handled.

##Operations Framework supports following operation:

• get
• post
• put
• delete

##Parameters If specification declares parameters for the operation, resolved values will be passed as handler arguments in the same order as in spec. For example if tags and limit parameter are specified as follow:

"/pets": {
      "get": {
        "description": "Returns all pets from the system that the user has access to",
        "operationId": "findPets",
        "produces": [
          "application/json",
          "application/xml",
          "text/xml",
          "text/html"
        ],
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "type": "string"
          },
          {
            "name": "limit",
            "in": "query",
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            }
          },
          "default": {
            "description": "unexpected error",
            "schema": {
              "$ref": "#/definitions/errorModel"
            }
          }
        }
      }
      }

then in handler they will be passed after meta object:

swaggerSpecMiddleware.host(app, {
    spec: 'spec.json',
    handlers: {
        getPets: function(meta, tags, limit){
            return {
                tags: tags,
                limit: limit
            }
        }
    }

});

Parameter inputs

Framework supports following parameter input sources:

• query
• heade
• path
• formData
• body

Parameter types and formats

Parameters are automatically converted to target types as follow:

Common Name	type	format	Comments
integer	integer	int32	signed 32 bits
long	integer	int64	signed 64 bits
float	number	float
double	number	double
boolean	boolean
string	string
byte	string	byte
date	string	date	As defined by full-date - RFC3339
dateTime	string	date-time	As defined by date-time - RFC3339

Errors and exceptions

Default behaviour

Following ruless obey regarding exceptions:

• When the called resource is not described in the spec, then next router declared in ExpressJS configuration can catch it
• When the called resource hits described in the spec operation which is unhandled, then it results in 404 page with message: "Unhandled operation"
• When the called resource hits described in the spec operation which throws generic exception, then it results in 404 page with message: "Unknown exception occured"
• When the called resource hits described in the spec operation which customized exception then it might results in error page with custom exception status or custom exception message

Customizing

Statuses and messages for above exceptions can be overridden with the configuration. Following attributes can be overridden:

• defaultExceptionStatus (default: 404) - request status for handled exceptions
• defaultExceptionMessage (default: "Unknown exception occured") - request message for handled exceptions
• unhandledOperationHandler (default: function () { throw {status: 404, message: 'Unhandled operation'}; }) - handler for unhandled operations

swaggerSpecMiddleware.host(app, {
    spec: 'spec.json',
    handlers: {...},
    defaultExceptionStatus: 403,
    defaultExceptionMessage: 'Customized unknown exception occured',
    unhandledOperationHandler: function () {
        throw {status: 403, message: 'Customized unhandled operation'};
    }

});