exegesis-express

What is exegesis-express?

exegesis-express is an npm package that provides a framework for building APIs using OpenAPI (formerly known as Swagger) specifications. It integrates with Express.js to allow developers to define their API endpoints, request/response validation, and middleware based on OpenAPI definitions.

What are exegesis-express's main functionalities?

API Endpoint Definition

This code demonstrates how to set up an Express server with exegesis-express middleware to handle API endpoints defined in an OpenAPI specification file.

const express = require('express');
const exegesisExpress = require('exegesis-express');
const path = require('path');

async function createServer() {
  const app = express();

  const options = {
    controllers: path.resolve(__dirname, './controllers'),
  };

  const exegesisMiddleware = await exegesisExpress.middleware(path.resolve(__dirname, './openapi.yaml'), options);

  app.use(exegesisMiddleware);

  app.use((err, req, res, next) => {
    res.status(err.status || 500).json({ message: err.message });
  });

  return app;
}

createServer().then(app => {
  app.listen(3000, () => {
    console.log('Listening on port 3000');
  });
}).catch(err => {
  console.error(err.stack);
  process.exit(1);
});

Request/Response Validation

This code sample shows how to enable request and response validation in an Express server using exegesis-express. The `validateResponses` option ensures that responses conform to the OpenAPI specification.

const express = require('express');
const exegesisExpress = require('exegesis-express');
const path = require('path');

async function createServer() {
  const app = express();

  const options = {
    controllers: path.resolve(__dirname, './controllers'),
    validateResponses: true, // Enable response validation
  };

  const exegesisMiddleware = await exegesisExpress.middleware(path.resolve(__dirname, './openapi.yaml'), options);

  app.use(exegesisMiddleware);

  app.use((err, req, res, next) => {
    res.status(err.status || 500).json({ message: err.message });
  });

  return app;
}

createServer().then(app => {
  app.listen(3000, () => {
    console.log('Listening on port 3000');
  });
}).catch(err => {
  console.error(err.stack);
  process.exit(1);
});

Custom Middleware Integration

This code demonstrates how to integrate custom middleware into an Express server that uses exegesis-express. The custom middleware logs a message for each request.

const express = require('express');
const exegesisExpress = require('exegesis-express');
const path = require('path');

async function createServer() {
  const app = express();

  const options = {
    controllers: path.resolve(__dirname, './controllers'),
  };

  const exegesisMiddleware = await exegesisExpress.middleware(path.resolve(__dirname, './openapi.yaml'), options);

  app.use(exegesisMiddleware);

  // Custom middleware
  app.use((req, res, next) => {
    console.log('Custom middleware executed');
    next();
  });

  app.use((err, req, res, next) => {
    res.status(err.status || 500).json({ message: err.message });
  });

  return app;
}

createServer().then(app => {
  app.listen(3000, () => {
    console.log('Listening on port 3000');
  });
}).catch(err => {
  console.error(err.stack);
  process.exit(1);
});

Other packages similar to exegesis-express

swagger-express-middleware

swagger-express-middleware is a package that provides Express middleware for working with Swagger (OpenAPI) documents. It offers features like request validation, mock responses, and more. Compared to exegesis-express, it focuses more on Swagger 2.0 and provides a different set of utilities for handling API requests.

express-openapi-validator

express-openapi-validator is a package that validates API requests and responses against an OpenAPI 3 specification. It integrates with Express.js and provides features like request validation, response validation, and security handling. It is similar to exegesis-express but focuses more on validation and security aspects.

openapi-backend

openapi-backend is a package that helps build and manage backend services using OpenAPI definitions. It provides features like request validation, routing, and response validation. Unlike exegesis-express, it is framework-agnostic and can be used with various server frameworks, not just Express.

README

exegesis-express

exegesis

n. An explanation or critical interpretation of a text, especially an API definition document.

-- No dictionary ever

This library implements an Express middleware for OpenAPI 3.x.

WARNING

🚨🚨 This is super beta. 🚨🚨

This is very much a work in progress. Wait for the v1.0.0 release, coming soon! :)

Usage

import express from 'express';
import http from 'http';
import * as exegesisExpress from 'exegesis-express';

async function createServer() {
    // See https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md
    const options {
        controllers: path.resolve(__dirname, './integrationSample/controllers'),
        securityPlugins: {
            sessionKey: sessionAuthSecurityPlugin
        }
    };

    const exegesisMiddleware = await exegesisExpress.middleware(
        path.resolve(__dirname, './integrationSample/openapi.yaml'),
        options
    );

    const app = express();
    app.use(exegesisMiddleware);
    app.use((err, req, res, _next) => {
        if(err) {
            res.writeHead(500);
            res.end(`Internal error: ${err.message}`);
        } else {
            res.writeHead(404);
            res.end();
        }
    });

    const server = http.createServer(app);
    server.listen(3000);
}

TODO

• Enable semantic-release
  • travis env set GH_TOKEN [your token here]
  • travis env set NPM_TOKEN [your token here]
  • Uncomment lines in travis.yml

Copyright 2018 Jason Walton