Fleek Router
Middleware for routing to controllers using swagger schema's.
Requirements:
- Node >= 6.0.0
- fleek-context
Usage
This package is to be used as middleware for Koa2 to route paths defined in swagger documentation using ctx.fleek.context
defined by fleek-context or an equivalent custom middleware.
npm install --save fleek-router
Examples
For a swagger example, refer to the test swagger json
const Koa = ;const fleekCtx = ;const fleekRouter = ; const SWAGGER = ; let app = ; app; let router = ; ctx app; // OR app;// TO MATCH EXAMPLE ABOVE:// controllers/// ├── bar.js [exports: get(ctx, next)]// ├── foo// | └── biz.js [exports: post(ctx, next)]// └── */** [exports: createBar(ctx, next)] app;
Documentation
new Router()
- Accepts
- Object - options
- Returns
- Router - returns a promise when called
Example
let myRouter = ;
Router.tag(name, operation)
- Accepts
- String - name of the tag to operate against. if the tag name is present in the request
ctx.fleek.context.tags[]
, the operation will be executed
- String - name of the tag to operate against. if the tag name is present in the request
- Returns
- Function - returns a promise when called
- Accepts
- Object -
ctx
(context) of the request - Function -
next
returns promise when called
- Object -
- Accepts
- Function - returns a promise when called
Example
app; app
Router.operation(operationId, operation)
- Accepts
- String - name of the tag to route to. if the tag name is present in the request
ctx.fleek.context.operationId
, the operation will be executed
- String - name of the tag to route to. if the tag name is present in the request
- Returns
- Function - returns a promise when called
- Accepts
- Object -
ctx
(context) of the request - Function -
next
returns promise when called
- Object -
- Accepts
- Function - returns a promise when called
Example
app;
Router.controllers(options) - Controller Directory
- Accepts
- One of
- String - path to controllers directory. Directory will be recursively read to create an object of controllers and operations
- Object - options or list object of controllers and operations
- Contains One of
- One of
- Returns
- Function - returns a promise when called
- Accepts
- Object - context of the request. must have
ctx.fleek.context
to perform validation - Function - returns promise when called
- Object - context of the request. must have
- Accepts
- Function - returns a promise when called
- Functionality
- The directory tree being parsed must contain flat or sud-directy
.js
files exporting operation functions - To execute a operation, the request
ctx.fleek.context
must contain data mapping it to the controller/operation - Routing:
- Controllers:
- To execute a method(
POST
,GET
,PUT
,DELETE
), the swagger documentation must specify the controller as the first tag(tags: []
) for the path+method - Every sub-directory or file name adds an expected tag to the required
ctx.fleek.context.tags[]
to route to the given operation- EG:
controllers/foo/bar.js[get(ctx, next) => { ... }]
will execute forctx.fleek.context = { method: 'get', tags: ['foo', 'bar'] }
- EG:
- To execute a method(
- Operations:
- Operations are identified by the name of the exported function(
module.exports[operationId]
), if it does not match a method type (POST
,GET
,PUT
,DELETE
) - To execute an operation, the swagger document must specify the
operationId
in the path+method configuration to match the exported function name - Operations are prioritized over controllers when routing
- Operation ID's are unique accross all controllers and operations, as speficied in the swagger 2.0 standard
- Operations are identified by the name of the exported function(
- Controllers:
- The directory tree being parsed must contain flat or sud-directy
Example
// Assuming directory structure:// controllers/// ├── bar.js [exports: get(ctx, next) => { ... }]// ├── foo// | └── biz.js [exports: post(ctx, next) => { ... }]// └── */** [exports: createBar(ctx, next) => { ... }] app; // OR app;
Router.controllers(controllers) - Controller Object
- Accepts
- Object - object of controllers and operations
- At least one of
controller
: Object - shallow or nested controllers, containg method operations (post|create
,get|read
,put|update
,delete|destroy
)`operation
: Object - shallow operations. propery keys expected to map tooperationId
- At least one of
- Object - object of controllers and operations
- Returns
- Function - returns a promise when called
- Accepts
- Object - context of the request. must have
ctx.fleek.context
to perform validation - Function - returns promise when called
- Object - context of the request. must have
- Accepts
- Function - returns a promise when called
- Functionality
- NOTE: the expected parameter object is also the compiled format of the directory system listed above
- To execute a operation, the request
ctx.fleek.context
must contain data mapping it to the controller/operation - Routing:
- Controllers:
- To execute a method(
POST
,GET
,PUT
,DELETE
), the swagger documentation must specify the controller as the first tag(tags: []
) for the path+method - Every nested property adds an expected tag to the required
ctx.fleek.context.tags[]
to route to the given operation- EG:
controller.foo.bar.get: (ctx, next) => { ... }
will execute forctx.fleek.context = { method: 'get', tags: ['foo', 'bar'] }
- EG:
- To execute a method(
- Operations:
- Operations are identified by the name of the exported function(
module.exports[operationId]
), if it does not match a method type (POST
,GET
,PUT
,DELETE
) - To execute an operation, the swagger document must specify the
operationId
in the path+method configuration to match the exported function name - Operations are prioritized over controllers when routing
- Operation ID's are unique accross all controllers and operations, as speficied in the swagger 2.0 standard
- Operations are identified by the name of the exported function(
- Controllers:
Example
app;
Authors
Built and maintained with by the Hart team.