ApiUiOptions

Options controlling how the API reference HTML page is rendered by ApiUiFactory.render(), expressApiUi(), and fastifyApiUi().

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

---

Options

Option	Type	Default	Description
pageTitle	string	document.info.title	<title> of the rendered page.
theme	'dark' | 'light'	'dark'	Color scheme.
customCss	string	—	Raw CSS injected after the built-in styles.
nonce	string	—	CSP nonce applied to inline <script> and <style> tags.
scope	string	—	Only include types, fields, and operations visible in this scope. When scopes is also set, this is the scope currently being rendered.
lang	string	—	Language the embedded API documentation is rendered in (matches ApiDocument#export({ lang })). Set by expressApiUi from ?lang=.
uiLang	string	lang	Language for the page's own interface texts (headings, buttons, tooltips). Resolved against @opra/api-ui's own i18n dictionaries — works even for a document with no translation bundles.
languages	string[]	—	Languages offered in the header's language selector. The selector is hidden when fewer than two remain. Defaults to the document's translation bundles union the UI's own shipped languages.
docLanguages	string[]	—	Subset of languages the document itself is documented in, so the selector can visually group them apart from interface-only ones.
scopes	string[]	—	All scope keys a reader can switch between (e.g. ['api', 'db']). When set with ≥ 2 entries the header shows a scope selector; switching causes a real navigation. Omit for a single fixed scope.
basePath	string	—	URL path the page is served from, excluding any scope segment. Used by the scope selector. Computed automatically by expressApiUi.
logo	ApiUiLogo | null	OPRA logo	Logo shown at the top-left of the header. Pass null to show no logo.
studio	boolean	false	Enable the documentation studio: a write surface on the same page, reached via ?edit=1 or the header button. Requires the document's TranslationStore to implement save — throws at startup otherwise.
studioParam	string	'edit'	Query parameter that switches the page between reading and writing mode. Set automatically by expressApiUi when studio is on.
authoring	object	—	Low-level authoring configuration. Set by oprimp docs:studio and expressApiUi. Prefer studio: true over setting this directly.

---

ApiUiLogo

interface ApiUiLogo {
  src: string;       // Image URL or data URI
  alt?: string;      // Alt text. Defaults to `label` or "Logo"
  href?: string;     // Click target. Defaults to the document's root page
  label?: string;    // Text shown next to the image
}

---

Example

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

app.use('/docs', expressApiUi(apiDocument, {
  pageTitle: 'Acme API',
  theme: 'light',
  logo: { src: '/img/logo.svg', label: 'Acme', href: 'https://acme.com' },
  scopes: ['public', 'internal'],
  studio: true,        // exposes ?edit=1 — protect behind auth in production
}));