Package Exports

openapi-express-router

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (openapi-express-router) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

OPENAPI-EXPRESS-ROUTER

An simple package to build and connect Express routes based on an OpenAPI 3 or Swagger 2 JSON spec.

Prerequisites

node >=10.22.0
express >=4.0.0

Installation

npm install openapi-express-router

// OR

yarn add openapi-express-router

Basic Usage

const express = require('express');
const { connectRoutes } = require('openapi-express-router');

#import OpenAPI 3 or Swagger 2 spec, controllers and middleware
const openApi = require('./api/open-api.json);
const controllers = require('./api/controllers.js);
const middleware = require('./api/middleware.js);

app = express();

const options = {
    controllers,
    middleware
};

const connect = connectRoutes(openApi, options);

connect(app);

Connecting Controllers

Controllers are uniquely identified in the Swagger 2 or OpenAPI 3 specification by the operationId i.e. the operationId must match the name of the controller.

"paths": {
    "/health/ping": {
        "get": {
            "summary": "Health check route",
            "description": "Returns pong if the server is healthy",
            "operationId": "healthController"
        }
    }
}

Controllers are connected via the options object and can be nested at any level e.g.

const options = {
    controllers: {
        healthController = (req, res, next) => res.status(200).json({message: req.body.message})
    }
}

// OR

const options = {
    controllers: {
        nestedControllers: {
            healthController = (req, res, next) => res.status(200).json({message: req.body.message})
        }
    }
}

If no controller is found which matches the operationId the following error will be thrown: No controller found for ${pathsKey}/${pathKey} which matches operationId: ${operationId}

Connecting Middleware

Middleware functions are optional but can be added to the Swagger 2 or OpenAPI 3 spec using the x-middleware array property.

"/health/ping": {
    "get": {
        "summary": "Health check route",
        "description": "Returns pong if the server is healthy",
        "operationId": "healthController",
        "x-middleware": [
            "healthMiddleware"
        ],
    }
}

Like controllers, middleware are connected via the options object and can be nested at any level e.g.

const options = {
    middleware: {
        nestedMiddleware: {
            healthMiddleware = (req, res, next) => {
                req.body.message = 'pong';
                next();
            }
        }
    }
}