Noodles Practicing Medicine

    exegesis-koa-cross
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    PRIVATE FORKED EXEGESIS PACKAGE

    Exegesis OpenAPI Engine

    NPM version Build Status Coverage Status Greenkeeper badge semantic-release

    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.

    Description

    Exegesis is a library for implementing server-side OpenAPI 3.x The library has been written in such a way that hopefully it will also be used to implement future versions of OpenAPI, or possibly even other API description standards altogether.

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

    Features

    Tutorial

    Check out the tutorial here.

    API

    compileApi(openApiDoc, options[, done])

    This function takes an API document and a set of options, and returns a connect-style middleware function which will execute the API.

    openApiDoc is either a path to your openapi.yaml or openapi.json file, or it can be a JSON object with the contents of your OpenAPI document. This should have the x-exegesis-controller extension defined on any paths you want to be able to access.

    options is described in detail here. At a minimum, you'll probably want to provide options.controllers, a path to where your controller modules can be found. If you have any security requirements defined, you'll also want to pass in some authenticators. To enable response validation, you'll want to provide a validation callback function via onResponseValidationError(). Exegesis's functionality can also be extended using plugins, which run on every request. Plugins let you add functionality like role base authorization, or CORS.

    compileRunner(openApiDoc, options[, done])

    This function is similar to compileApi; it takes an API document and a set of options, and returns a "runner". The runner is a function runner(req, res), which takes in a standard node HTTP request and response. It will not modify the response, however. Instead it returns (either via callback or Promise) and HttpResult object. This is a {headers, status, body} object, where body is a readable stream, read to be piped to the response.

    writeHttpResult(httpResult, res[, done])

    A convenience function for writing an HttpResult from a runner out to the response.

    Example

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

    Internal Workings

    Internally, when you "compile" an API, Exegesis produces an ApiInterface object. This is an object that, given a method, url, and headers, returns a resolvedOperation - essentially a collection of functions that will parse and validate the body and parameters, has the controller that executes the functionality, etc... The only current implementation for an ApiInterface is the oas3/OpenApi class. Essentially this class's job is to take in an OpenAPI 3.x.x document, and turn it an ApiInterface that Exegesis can use. In theory, however, we could parse some other API document format, produce an ApiInterface, and Exegsis would still be able to run it.

    Install

    npm i exegesis-koa-cross

    DownloadsWeekly Downloads

    88

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    311 kB

    Total Files

    159

    Last publish

    Collaborators

    • ondrej-111