KOX
koa module addon, make write api server more easier. Design an api style, combine with swagger(inspired by hapi-swagger).
Installation
$ npm i kox
Example
// this will return an koa instance, so all koa properties are supported by kox.const app = const apis = method: 'get' path: '/' { ctx return "hello world" }appapp
Getting started
API
app
Because kox
is just koa
addon, so all koa app api
are supported.
You can read koa docs.
In kox, i use koa-body
to handle request body parsing, so you dont need to add this middleware again in your project, the default body parser setting as follow:
jsonLimit: '100KB' formLimit: '50KB' multipart: true formidable: uploadDir:
You can modify body parser setting when initial kox instance:
const app =
Controller
Kox add two controller related api to koa instance:
app.controller
app.loadCtrls
app.controller
This api is used to add an controller.
const fooController = name: 'foo' ...// this operation add controller to app._controllers, we will using these controllers in api definitions.app
app.loadCtrls
This api is used to add multiple controllers. I usually use it with require-dir
module. You can see code in example.
const requireDir = const controllers = app
Controller Class
app.controller
and app.loadCtrls
are all used to create Controller
, and most design of
Controller
are inspired by sundae which based on express. But I make action to be more functional, and handle the context as an argument in action. And I prefer put all dependencies in context, rather then require them in the begin of a code file. I think that will make action easy to test in real project.
-
Controller#mixin
mixin
will add actions tothis._actions
of controlller. And actions can be invoked as api handler or used to be a hookconst mixins =ctrl -
Controller#action
action
will add an action tothis._actions
ctrlaction'action1' {...} -
Controller#before
before
will set an action as pre hook of other action, and it take options to indicate actions to hook// this will hook `hello` action before `foo` and `bar`ctrl// this operation will return an generator combine hello and fooctrl -
Controller#after
The same asbefore
, but add post hook to actions// this operation will add post hook to every actions except action named marriedctrl -
Controller#invoke
Will return a generator, used inkoa-router
module.ctrl
Swagger API
I used to write business code and document of code separately. I think that way to write code cant make me more productive. I want to Document can decribe code and code can be document. And Swagger have done this. I found hapi-swagger is really awesome project to do this. But the way to write code in hapi is not my tea, so i rebuild kox
api describe
method: 'get' path: '/hello' handler: 'controller.action' // or you can write an function directly tags: 'Hello' summary: 'say hello' description: 'this api will return hello world' // validate definition is the same as hapi, using joi as validator validate: payload: Joiobject... params: ... query: ... headers: ... responses: 200: description: 'success' schema: Joiobject{} // we validate response by schema
LICENSE
MIT
TODO
- Generate Swagger Json Route
- Auto route api
- Full Example
- Full documents
- Rendering API