swagger-middlewares

swagger-middlewares

Provides generic HTTP middlewares exposing swagger defination.

Install

npm install swagger-middlewares

Methods

• init()
• validateSchema()
• koa.spec()
• koa.ui()
• koa.validator()

init(swaggerRootDocument, [otherOptions])

• Returns an instance
• Options
  • swaggerRootDocument: Overrides standard swagger root document object containing (apiVersion, host, info, basePath)
  • otherOptions.swaggerSpecPath: A path or an array of path to load Swagger specification in yaml format, only accepts yml or yaml extension).

<instance>.validateSchema([options], [onError])

• Prints out error message about Swagger Schema validation error

<instance>.koa.spec([uri])

• Returns a Swagger UI Koa middleware
• Options
  • uri: optional URI path, default to /api-docs

<instance>.koa.ui([uri])

• Returns a Swagger UI Koa middleware. You may need to include swagger-ui npm module in your project by npm install --save swagger-ui
• Options
  • uri: optional URI path, default to /swagger/ui

<instance>.koa.validator()

• Returns an validator middleware. Validator usage can be found at swagger-model-validator

Usage Example

// initialization
let pkg     = require('package.json');
let swagger = require('swagger-middlewares').init({
  host: 'localhost:3000',
  info: {
    version: pkg.version,
    title: pkg.name,
    description: pkg.description
  }
}, {
  // A path or an array of paths to load yaml Swagger specification
  swaggerSpecPath: path.join(__dirname, 'src/controller')
});


let app        = koa();

// This will prints out errors if swagger schema is not valid
swagger.validateSchema();

// expose swagger JSON specification
// curl http://localhost:3000/api-docs
app.use(swagger.koa.spec());

// expose swagger user interface
// curl http://localhost:3000/swagger/ui
app.use(swagger.koa.ui());

// creates a validator in the koa generator context
// do anything with the validation results
// exports.get = function * () { 
//   this.validator.swagger.validateModel('ModelName', this.body);
// }
app.use(swagger.koa.validator());

Limitation

• Only support Swagger Specification 2.x
• Only Provides Koa middleware at the moment
• Only Support one instance per node process
• Limited Validation features, middleware validator is available but it does not force validation