You know how it is. You’re developing, you need a library, you open npmjs.com and you start searching. Millions of libraries. Each one does something, some do more, some less, some better, some worse. But each one fills the disk in the node_modules directory ? .
But what to do if you can’t find what you’re looking for? You program your own, surely!
But let’s start from the beginning. I am not sure you know this, but we program the API servers in node.js. That isn’t anything unusual nowadays, an above-average high school student can handle that. The essence of our work lies in the design of the server, the design of inputs and outputs and in business logic. And documentation. Who likes to write documentation? Probably no one. But everyone, be it a developer or a technically proficient customer, likes to read and criticize it.
So a few years ago we decided to develop in a way that has the documentation as its basis. We found a very pleasant union in the OpenAPI Specification V3 (OAS3).
What does it bring us?
- API description, definition of parameter schemes on input and output
- automatically generated documentation, which also serves as a test of requests
- and depending on the framework used, an automatic router and an input validator
And precisely the last point is the problem in node.js. We use the koa.js library as the basis of the http server. It has almost twice the performance of the express. It has a nice middleware scheme. It uses generators and asynchronous code. It’s easy to implement and doesn’t layer unnecessary ballast over the native http(s) module.
But we searched in vain for a library that would take the OpenAPI specification on one hand, the Koa application on the other, and combine it with all the advantages. And so we made a small, 500-line library ourselves. It’s a compilation of several libraries, each of which performs its function and does it well.
Koa + OAS3 = KOAS3
With a separate library, we killed several flies with one blow:
- The library will create a router that you will deploy to an existing Koa application as middleware. This way you can integrate it among other already existing routers and middlewares, or make only a part of the application using OpenAPI. This is useful if you are dealing with a problem that doesn’t support OAS3, or for example, when you need to attach a stream to a URL or a Websocket server.
- The definition of security (authentication and authorization) is taken from OpenAPI and each request is automatically protected as specified in OAS3. Of course, you have to write the individual security handlers yourself ?
- Each request parameter is checked and validated against the specification. So in the controller, you don’t have to worry about whether the user ID arrived as an integer or a string. If you specified it as an integer, it is 100 % integer, otherwise KOAS3 will return an error http response 400 Bad Request.
- As a bonus, KOAS3 will create a route on which it will attach a neat documentation, usually on /docs – for example, a specification for our Pages application.
How is it implemented? Everything you need can be found on the npm koas3 package page.
We currently have almost half of the API services in the SportNet project on KOAS3. During that time, we have found features that are missing and we need to add them. Small roadmap:
- Create support for multiple interdependent OpenAPI files
- Create support for external references in the OpenAPI specification
- Add custom validator formats for parameters, for example, we would like to add to those existing a date-time, or email as well as url and ObjectId.
- And, of course, add automated tests over the library with code coverage of 100 % ?
KOAS3 is currently in version 0.0.5. We have a long way to go to version 1.0.0. Try it and help us with that. An Open-source project is only as good as its contributors.
