Guides

Configuration

Every option, and how to pass it from JavaScript, React, HTML attributes or the CLI. The names are the same everywhere; HTML attributes use their kebab-case form.

Options

OptionTypeDefaultDescription
specUrlstringURL of the OpenAPI document (JSON or YAML). Relative $refs resolve against it.
specobjectThe document as an object. Takes precedence over specUrl.
titlestringinfo.titleText in the header, localized through x-i18n when it comes from the document.
logostring, object or React nodeHeader logo instead of the title. See Logo.
localestringUI language, controlled: the reader's choice is reported through onLocaleChange and applied only when you pass it back.
defaultLocalestring"en"Starting UI language when locale is not given; the reader can switch afterwards.
onLocaleChange(locale) => voidCalled when the reader picks a language.
messagesobjectExtra languages or overrides of the interface strings. See Localization.
proxyUrlstring or nullnullEndpoint that relays Try requests from your server. See Try it.
featuresobjectall trueTurn parts of the interface off. See Features.
defaultSnippetstring"shell:curl"Code sample shown first, as language:client. See Code samples.
theme"light" or "dark"reader's choiceStart in this theme instead of the reader's stored choice or system setting. Add features: { themeToggle: false } to lock it.
storagePrefixstring"oaspect"Prefix of the keys oaspect keeps in localStorage and sessionStorage.
urlParamstring or null"url"Query parameter that loads another document (?url=https://…). null turns it off.
lazyboolean or "auto""auto"Render operations and models only when they come near the viewport. "auto" does it for documents with more than 40 operations.
view"reference" or "print""reference""print" opens the print view. See Print and PDF.
printobjectBook style, paper, cover logo, subtitle, organization, date. See Print and PDF.

Features

KeyDefaultTurns off
tryIttrueThe Try button and dialog
modelstrueThe Models section and its sidebar entries
sourceMenutrueThe Source menu (load another URL or a local file)
languageSwitchertrueThe UI language menu
printtrueThe printer button (print view)
themeToggletrueThe light/dark toggle
js
Oaspect.init("#docs", {
  specUrl: "/openapi.yaml",
  features: { tryIt: false, sourceMenu: false },
});

In Oaspect.init and the web component, logo is an image URL or an object:

js
logo: {
  light: "/logo.svg",      // light theme, or both when dark is missing
  dark: "/logo-dark.svg",  // dark theme
  alt: "Acme",
  label: "API Reference",  // text next to the logo on wide screens
}

In React, logo is any node; the Logo component gives the same light/dark behavior:

jsx
import { ApiReference, Logo } from "@oaspect/react";

<ApiReference specUrl="/openapi.yaml" logo={<Logo light="/logo.svg" dark="/logo-dark.svg" alt="Acme" label="API Reference" />} />

Passing options

JavaScript API

The standalone script defines window.Oaspect:

MemberDescription
Oaspect.init(target, options)Renders into target (an element or a selector) and returns a handle.
Oaspect.hydrate(target, options)Attaches to markup prerendered by oaspect build. options must match the ones used to prerender.
Oaspect.versionThe bundle version.
handle.update(options)Merges the new options into the current ones and re-renders.
handle.destroy()Unmounts the reference.
js
const docs = Oaspect.init("#docs", { specUrl: "/v1/openapi.yaml" });

// later: switch the document or the language
docs.update({ specUrl: "/v2/openapi.yaml" });
docs.update({ locale: "tr" });

React props

<ApiReference> takes the options as props. Type definitions ship with the package.

jsx
<ApiReference
  specUrl="/openapi.yaml"
  defaultLocale="tr"
  defaultSnippet="python:requests"
  features={{ models: false }}
  proxyUrl="/api/proxy"
/>

HTML attributes

<oaspect-reference> and the auto-mounting script tag read string options from attributes. On the script tag, prefix them with data-.

AttributeOption
spec-urlspecUrl
titletitle
localelocale
default-localedefaultLocale
proxy-urlproxyUrl
themetheme
storage-prefixstoragePrefix
default-snippetdefaultSnippet
logo, logo-dark, logo-alt, logo-labellogo (light, dark, alt, label)
viewview
print-style, paperprint (style, paper)
hidefeatures: a comma-separated list of try-it, models, source-menu, language-switcher, theme-toggle, print
html
<oaspect-reference
  spec-url="/openapi.yaml"
  default-locale="tr"
  logo="/logo.svg"
  logo-dark="/logo-dark.svg"
  hide="source-menu,models"
></oaspect-reference>
html
<script
  src="https://cdn.jsdelivr.net/npm/oaspect"
  data-spec-url="/openapi.yaml"
  data-proxy-url="/api/proxy"
  data-hide="source-menu"
></script>

Options that are not strings (spec, messages, onLocaleChange, lazy, urlParam) need Oaspect.init or the element's spec property.

CLI flags

oaspect build and oaspect serve take --title, --locale (as defaultLocale), --theme and --logo. See CLI.

What the browser stores

Preferences live in the reader's browser, under keys that start with storagePrefix and a colon (oaspect:theme). Nothing is sent anywhere.

KeyStorageHolds
themelocallight or dark once the reader toggles it
languagelocalThe selected code sample (language:client)
token, credentialslocalBearer token and security scheme credentials entered in the Connection panel
request-modelocalProxy or direct sending
skip-write-confirmsession"Don't ask again" for write requests, for this tab only

Give each reference on a domain its own storagePrefix so they do not share tokens.

The out-of-date notice

When the document comes from an endpoint that answers with the header x-oaspect-spec-source: fallback, the reference shows a notice that the reader sees a stored copy. createSpecHandler sets it when the live document cannot be loaded (see Server helpers).