npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

exegesis-express

v4.0.0

Published

Express middleware to handle OpenAPI 3.x.

Downloads

1,831,670

Readme

exegesis-express

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 an Express middleware for OpenAPI 3.x.

Features

Tutorial

Check out the tutorial here.

Usage

Calling exegesisExpress.middleware(openApiFile, options) will return a Promise which resolves to a connect/express middleware (alternatively you can call exegesisExpress.middleware(openApiFile, options, done), if callbacks are your thing).

openApiFile 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 can be anything you can pass to exegesis. 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.

Where to put Exegesis-Express in your middleware stack

Exegesis-express should appear near the top of your middleware stack, before any body parsers. This is because exegesis will take care of parsing the body for you, and it can't do that if the body has already been read. If you put a body parser ahead of exegesis-express, exegesis will try to use req.body if it's there.

Servers section

OpenAPI 3.x lets you specify what servers your API is available on. For example:

servers:
  - url: "/api/v2"

By default, exegesis will take 'servers' into account when routing requests, so if you have the above servers section, and a path in your API called "/users", then exegesis will only match the route if the incoming requests has the URL "/api/v2/users".

If you have path templates in your servers, the variables will be available to your controllers via context.params.server.

If you specify the ignoreServers option, however, exegesis will ignore the servers section, an route purely based on your paths. This lets you do something like:

const exegesisMiddleware = await exegesisExpress.middleware(
  path.resolve(__dirname, "./openapi.yaml"),
  { ignorePaths: true }
);
app.use("/api/v2", exegesisMiddleware);

which means non-api paths will not even be sent to the exegesis middleware.

Example

import express from "express";
import path from "path";
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, "./controllers"),
  };

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

  const app = express();

  // If you have any body parsers, this should go before them.
  app.use(exegesisMiddleware);

  app.use((req, res) => {
    res.status(404).json({ message: `Not found` });
  });

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

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

Copyright 2018 Jason Walton