0.0.9 • Published 8 years ago
swagger-middlewares v0.0.9
swagger-middlewares
Provides generic HTTP middlewares exposing swagger defination.
Install
npm install swagger-middlewares
Methods
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 acceptsyml
oryaml
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 bynpm 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