openapi-express-router
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.6 • Public • Published

    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();
                }
            }
        }
    }
    

    Install

    npm i openapi-express-router

    DownloadsWeekly Downloads

    2

    Version

    1.0.6

    License

    ISC

    Unpacked Size

    10.9 kB

    Total Files

    7

    Last publish

    Collaborators

    • alexanderdavies