request + response sanitation/validation against swagger specs
Creating APIs is often boring and repetitive because you need to ensure that all the data flowing respects a certain format. Often we miss something and a security flaw or a source of incoherence appears.
One solution is to test your API against a complete spec: either by testing each combination of parameters & results by hand resulting in even more boring tests than the actual implementation or by using a tool like swagger to simplify checks. The second solution is already a good step in the right direction.
But that's not enough!
If the spec can be used to check and sanitize requests and tail responses to make them compliant with the spec, we can get rid of a lot of boilerplate code. koa-swagger does that.
$ npm install --save koa-swagger
koa-swagger does not provide anything else than what he has been created for: check and sanitize. That's why you'll need to provide other middleware before injecting koa-swagger.
The choice of which middleware you put before is entirely up to you but all you need should be bodyparser (it depends on your API's needs actually):
$ npm install --save koa-bodyparser
You'll also need to implement the spec! For that, use what you prefer, vanilla-koa or route for example:
$ npm install --save koa-route
Here's a one-liner:
$ npm i --save koa koa-bodyparser koa-swagger koa-route
After that, it's really simple:
Here's an example:
var SPEC =swagger: "2.0"info:title: "Hello API"version: "1.0.0"basePath: "/api"paths:"/hello/:name":"get":tags: "Hello"summary: "Says hello"parameters:name: "name"in: "path"type: "string"default: "World"name: "punctuation"in: "query"type: "string"required: trueresponses:"200":description: "Everything went well :)"schema: $ref: "#/definitions/Message""400":description: "Issue with the parameters"definitions:Message:required: "message"properties:message:type: "string";var app = ;app;app;var _ = ;app;
Here are some things I'm planning to do when time arises:
You have to write PRs if you want me to merge something into master.
I need to accept your feature or fix (not a problem usually!) although the tests must pass (you should test new features) and the linter must pass too.
Here's a command to check everything at once (the CI will complain otherwise):
$ npm test && npm run lint && echo ok
If it outputs
ok, that's usually a good sign!