exegesis

What is exegesis?

Exegesis is a library for building REST APIs using OpenAPI (formerly known as Swagger). It allows you to define your API using an OpenAPI specification and then automatically handles request validation, response validation, and routing based on that specification.

What are exegesis's main functionalities?

Request Validation

This code demonstrates how to set up request validation using Exegesis. It uses an OpenAPI specification file to automatically validate incoming requests against the defined API schema.

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

const app = express();

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

exegesisExpress.middleware(path.resolve(__dirname, './openapi.yaml'), options)
  .then((middleware) => {
    app.use(middleware);
    app.listen(3000, () => {
      console.log('Listening on port 3000');
    });
  });

Response Validation

This code demonstrates how to set up response validation using Exegesis. It ensures that the responses sent by the server conform to the OpenAPI specification.

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

const app = express();

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

exegesisExpress.middleware(path.resolve(__dirname, './openapi.yaml'), options)
  .then((middleware) => {
    app.use(middleware);
    app.use((req, res, next) => {
      res.json({ message: 'Hello, world!' });
    });
    app.listen(3000, () => {
      console.log('Listening on port 3000');
    });
  });

Routing

This code demonstrates how to set up routing using Exegesis. It automatically routes incoming requests to the appropriate controller based on the OpenAPI specification.

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

const app = express();

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

exegesisExpress.middleware(path.resolve(__dirname, './openapi.yaml'), options)
  .then((middleware) => {
    app.use(middleware);
    app.listen(3000, () => {
      console.log('Listening on port 3000');
    });
  });

Other packages similar to exegesis

swagger-express-middleware

Swagger Express Middleware is a collection of middleware for Express.js that automatically validates requests, responses, and more using a Swagger (OpenAPI) specification. It is similar to Exegesis in that it provides request and response validation, but it does not offer as seamless integration with controllers and routing.

express-openapi-validator

Express OpenAPI Validator is a middleware for Express.js that validates requests and responses against an OpenAPI 3 specification. It is similar to Exegesis in terms of validation capabilities but does not provide built-in routing or controller integration.

openapi-backend

OpenAPI Backend is a library for building and routing APIs using OpenAPI definitions. It focuses on routing and handling requests based on the OpenAPI specification, similar to Exegesis, but it is more lightweight and does not include built-in validation.

README

Exegesis OpenAPI Engine

exegesis

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

-- No dictionary ever

This library implements a framework-agnostic server side implementation of OpenAPI 3.x.

You probably don't want to be using this library directly. Have a look at:

• exegesis-express - Middleware for serving OpenAPI 3.x APIs from express.
• exegesis-connect - Middleware for serving OpenAPI 3.x APIs from connect.

WARNING

🚨🚨 This is super beta. 🚨🚨

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

Usage

import * as path from 'path';
import * as http from 'http';
import * as exegesis from 'exegesis';

// See https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md
const options = {
    controllers: path.resolve(__dirname, './src/controllers')
};

// `compileApi()` can either be used with a callback, or if none is provided,
// will return a Promise.
exegesis.compileApi(
    path.resolve(__dirname, './openapi/openapi.yaml'),
    options,
    (err, middleware) => {
        if(err) {
            console.error("Error creating middleware", err.stack);
            process.exit(1);
        }

        const server = http.createServer(
            (req, res) =>
                middleware(req, res, (err) => {
                    if(err) {
                       res.writeHead(err.status || 500);
                       res.end(`Internal error: ${err.message}`);
                    } else {
                        res.writeHead(404);
                        res.end();
                    }
                })
        );

        server.listen(3000);
    }
);

See options documentation for details about options.