openapi-backend

OpenAPI Backend

Non-opinionated middleware tools for building API backends with the OpenAPI standard previously known as Swagger.

You can use OpenAPI Backend as middleware to handle routing and/or input validation in any Node.js API backend.

Features

• Build APIs by describing them in OpenAPI document specification and importing them via YAML or JSON files or as a JS object
• Register handlers for API operations for routing in your favourite Node.js backend like Express, Hapi, AWS Lambda or Azure Functions
• Use JSON Schema to validate API requests. OpenAPI Backend uses the AJV library under the hood for performant validation

(Currently only OpenAPI v3.0.0+ is supported)

Quick Start

Full example projects included in the repo

npm install --save openapi-backend

import OpenAPIBackend from 'openapi-backend';

const api = new OpenAPIBackend({
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
    paths: {
      '/pets': {
        get: {
          operationId: 'getPets',
          responses: {
            200: { description: 'ok' },
          },
        },
      },
      '/pets/{id}': {
        get: {
          operationId: 'getPetById',
          responses: {
            200: { description: 'ok' },
          },
        },
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            schema: {
              type: 'integer',
            },
          },
        ],
      },
    },
  },
  handlers: {
    // your platform specific request handlers here
    getPets: async (req) => ({ status: 200, body: 'ok' }),
    getPetById: async (req) => ({ status: 200, body: 'ok' }),
    notFound: async (req) => ({ status: 404, body: 'not found' }),
    validationFail: async (err, req) => ({ status: 400, body: JSON.stringify({ err }) }),
  },
});

// initalize the backend
api.init();

Express

import express from 'express';

const app = express();
app.use((req, res) => api.handleRequest(req, req, res));
app.listen(9000);

Hapi

import Hapi from 'hapi';

const server = new Hapi.Server({ host: '0.0.0.0', port: 9000 });
server.route({
  method: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  path: '/{path*}',
  handler: (req, h) =>
    api.handleRequest(
      {
        method: req.method,
        path: req.path,
        body: req.payload,
        query: req.query,
        headers: req.headers,
      },
      req,
      h,
    ),
});
server.start();

AWS Serverless (Lambda)

// API Gateway Proxy handler
module.exports.handler = (event, context) =>
  api.handleRequest(
    {
      method: event.httpMethod,
      path: event.path,
      query: event.queryStringParameters,
      body: event.body,
      headers: event.headers,
    },
    event,
    context,
  );

Azure Serverless Function

module.exports = (context, req) =>
  api.handleRequest(
    {
      method: req.method,
      path: req.params.path,
      query: req.query,
      body: req.body,
      headers: req.headers,
    },
    context,
    req,
  );

Contributing

OpenAPI Backend is Free and Open Source Software. Issues and pull requests are more than welcome!