HttpApiScalar unstable

Scalar documentation UI for declarative HttpApi contracts.

Use this module to mount a browser-based API reference on an HttpRouter without writing or storing a separate OpenAPI file. The route renders an HTML page containing the OpenAPI document produced from the supplied HttpApi and boots Scalar in the browser.

4 exports Since v4.0.0 Source

Layers

layer

unstable

Since v4.0.0

Mounts a Scalar API reference page for an HttpApi using the bundled Scalar script.

Details

The route serves the OpenAPI specification generated from the API at the configured path, defaulting to /docs.

Signature

declare function layer<Id extends string, Groups extends Constraint>(api: HttpApi<Id, Groups>, options?: {
  readonly path?: `/${string}`;
  readonly scalar?: ScalarConfig;
}): Layer<never, never, HttpRouter>

layerCdn

unstable

Since v4.0.0

Mounts a Scalar API reference page for an HttpApi that loads Scalar from jsDelivr.

Details

The route serves the OpenAPI specification generated from the API at the configured path, defaulting to /docs; version selects the Scalar package version loaded from the CDN.

Signature

declare function layerCdn<Id extends string, Groups extends Constraint>(api: HttpApi<Id, Groups>, options?: {
  readonly path?: `/${string}`;
  readonly scalar?: ScalarConfig;
  readonly version?: string;
}): Layer<never, never, HttpRouter>

Models

ScalarConfig

type unstable

Since v4.0.0

Configuration passed to the embedded Scalar API reference UI.

Details

This configuration follows Scalar's API reference configuration: https://github.com/scalar/scalar/blob/main/documentation/configuration.md

Signature

type ScalarConfig = {
  authentication?: {
    preferredSecurityScheme?: string | Array<string | Array<string>> | null;
  };
  baseServerURL?: string;
  customCss?: string;
  customFetch?: string;
  darkMode?: boolean;
  defaultOpenAllTags?: boolean;
  favicon?: string;
  forceDarkModeState?: "dark" | "light";
  hideDarkModeToggle?: boolean;
  hideModels?: boolean;
  hideSearch?: boolean;
  hideTestRequestButton?: boolean;
  layout?: "modern" | "classic";
  proxyUrl?: string;
  showOperationId?: boolean;
  showSidebar?: boolean;
  theme?: ScalarThemeId;
  withDefaultFonts?: boolean;
}

ScalarThemeId

type unstable

Since v4.0.0

Theme preset identifier accepted by the Scalar API reference UI.

Signature

type ScalarThemeId = "alternate" | "default" | "moon" | "purple" | "solarized" | "bluePlanet" | "saturn" | "kepler" | "mars" | "deepSpace" | "laserwave" | "none"