@theneo/express

Express Router that serves the Theneo API Reference UI and static assets from @theneo/vanilla.

Installation

yarn add @theneo/express express

In this monorepo: from the repository root, install and build so node_modules/@theneo/vanilla/dist exists:

yarn install
yarn turbo run build --filter=@theneo/express

See the root README and express example.

Usage

## Auto-scan mode (zero-config)

Install [`@theneo/openapi-scanner`](../../../packages/openapi-scanner) and set `scan: true` — the middleware generates the OpenAPI spec from your source code at boot and serves it at `<mount>/openapi.json`. No `openapi.json` to write, no JSDoc annotations required.

```ts
import express from "express";
import { apiReference } from "@theneo/express";

const app = express();

// … your routes …

app.use("/api/docs", apiReference({
  title: "My API",
  scan: true,   // or scan: { entries, info, servers, … } for overrides
}));

app.listen(3000);

The scanner runs once at Express boot. Reboot to pick up route changes (or use theneo-scan dev as a separate watch process).

Manual mode (bring your own spec)

import express from "express";
import { apiReference } from "@theneo/express";

const app = express();

app.get("/openapi.json", (_req, res) => res.sendFile("openapi.json"));

app.use(
  "/docs",
  apiReference({
    specUrl: "/openapi.json",
    title: "My API",
  }),
);

app.listen(3000);

Visit http://localhost:3000/docs.

apiReference(config)

Returns an express.Router() with:

| Method | Path | Description | | ------ | ---------- | ------------------------------------ | | GET | / | HTML shell that boots the viewer | | GET | /theneo.js | UMD bundle from @theneo/vanilla | | GET | /theneo.css | Styles from @theneo/vanilla |

Config

All config properties are forwarded verbatim to the in-browser viewer, so any current or future ApiReferenceProps works. Common ones:

• specUrl — OpenAPI document URL. Same-origin paths like /openapi.json work.
• spec — Optional inline OpenAPI object (serialized into the page).
• theme — "light" or "dark".
• title — Document and UI title.
• url — Deprecated alias for specUrl, kept for backwards compatibility.

Peer dependency

• express ^4.18 or ^5.x