Skip to main content

expressApiUi

Express middleware factory that mounts the @opra/api-ui reference page at a given route. Handles scope-per-URL and language-per-request rendering, with optional documentation studio support.

import { expressApiUi } from '@opra/api-ui';

Signature​

function expressApiUi(
  document: ApiDocument,
  options?: ApiUiOptions,
): RequestHandler

Returns an Express RequestHandler (compatible with app.use(path, handler)).

Usage​

import express from 'express';
import { expressApiUi } from '@opra/api-ui';

const app = express();

app.use('/reference', expressApiUi(apiDocument, {
  pageTitle: 'My API',
  theme: 'dark',
}));

With scope selector​

app.use('/reference', expressApiUi(apiDocument, {
  scopes: ['public', 'internal'],
}));
// GET /reference/public/  → public scope
// GET /reference/internal/ → internal scope

With documentation studio​

// ⚠ This is a write endpoint. Protect it behind authentication.
app.use('/reference', requireAdmin, expressApiUi(apiDocument, {
  studio: true,
}));
// GET /reference/        → reference page
// GET /reference/?edit=1 → studio (writing mode)

What it handles​

expressApiUi derives the mount prefix from Express's req.baseUrl (already stripped by app.use) so sub-paths like GET /reference/schema/root.json, GET /reference/openapi/root.json, and GET /reference/codegen/client.js all work automatically. Each scope + language combination is rendered once and cached in memory.

See also​