Overal Architecture
To make the best out of swagger-node-runner, one needs to understand the moving parts in it, how they relate to each other, and how they relate to the user code.
First layer is pipeworks - a package that focuses on building flows out of potentially reusable handlers.
A flow is basically a set of handlers, where every link in the pipe holds a reference to the handler, and is called a fitting. Very similarly to async.waterfall, each handler is passed with the output the previous handler yielded. The pipeworks layer takes care of pipe isolation and reuse, and provides a basis for error handling.
Second layer is bagpipes - a package that is based on pipeworks and provides 3 things:
- formulates pipeworks fittings into a concrete standard, specific for it's usecase. The standard aims to express each fitting in it's own reusable file.
- Having such standard,
bagpipescomes with an implemented set of core fittings that do very simple tasks as basic lego-stones, on top of which a user may add it's own fittings. - Having fittings described as pipes - it lets the user describe his pipes in configuration instead of code, aiming to facilitate reusability, readability, and extensibility.
As far as flow-control concerns - swagger-node-runner rides on top of bagpipes, describing the request-processing flow as pipe, where every traditional swagger middleware (params, validate, security, router) is expressed as a bagpipes fitting.
Framework Compatibility is accomplished by adapting each framework separately into the simplest and lowest-level implementation - connect.
At the time of writing of this doc, swagger-node-runner includes framework-specific implementation details for few frameworks, however, there is a named trend to keep in swagger-node-runner only the core base, and move the framework-specific parts to the framework-specific packages.
Open-api spec is a text format to describe the operations parameters, responses and security definitions (modernly done in YAML, JSON is supported as well). The data available in the swagger-api spec document is represented as an Object Model that facilitates the work with it using sway. Sway helps in:
- reading oapi spec doc from file
- validating oapi spec doc
- maturing the spec to final values - i.e - resolving $ref statements, so you don't have to jump around
- converiting the tree into an inter-connected graph (if you have one node on the graph - you can access any point in the graph)
- facilitating navigation on the graph through a comprehensive API.
swagger-node-runner uses sway for all these purposes, and enriches contexts passed to user-code with the api or the operation in respect to what the user is likely need.
swagger-node-runner relays on the package config, which basically expects a set of cascading files that end up as a model of active values per environment.
swagger-node-runner expects a root key called swagger, and in it sections that pass to it's respective parts, the bigger of which is swagger.bagpipes section - that naturally is passed to bagpipes.