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.

Flow Managment

Request-Processing Flow is depicted in the drawing with dark blue arrows, one can follow the request flow, as it starts and ends from the clients on the right. However, to get to that - the system should be ready, where Initiation Flow is depicted by yellow arrows. To make sense of all the details there, one should distinct between few layers.

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:

1. 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.
2. Having such standard, bagpipes comes 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.
3. 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

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 Object Model

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:

1. reading oapi spec doc from file
2. validating oapi spec doc
3. maturing the spec to final values - i.e - resolving $ref statements, so you don't have to jump around
4. converiting the tree into an inter-connected graph (if you have one node on the graph - you can access any point in the graph)
5. 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.

Configuration

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. Here the beauty of the power of bagpipes emerges, as a user can insert his own extensions and add-hock adapters in the flow as atomic steps, unaware of the environment - and hence easily proofed and tested. These extensions can be project-code, and node packages (both proprietary or open-source)