`html/render-shell` — ReDoc HTML shell renderer

(no submodules)

Purpose

This module exposes renderRedocShell, the pure function that produces the ReDoc HTML shell consumed by both the global and per-plugin handlers. It embeds the OpenAPI document URL into a <redoc spec-url="…"> custom element, ships a JSON option island for the runtime to read, and injects the runtime runtime asset reference based on the chosen asset strategy. Keeping the renderer separate from the handler factories lets host operators embed the shell in custom adapters (e.g. SSR, Edge functions) without reaching for the handler builder.

Features

HTML-escapes every user-supplied value (title, openapiUrl, etc.) so option strings cannot break out of attribute or text-node scope.
Inlines the runtime body when strategy === "inline" and emits a <script src="…"> tag for cdn / bundled strategies.
Embeds theme, hideDownloadButton, nativeScrollbars, and expandResponses into the JSON options island the runtime reads.
Tags the body element with data-redoc-theme so external stylesheets can override the colour scheme.
Pure — no I/O, no clocks, no globals.

Usage: Basic

import { renderRedocShell } from "@suaveplan/api-openapi-ui-redoc/html";
import {
    parseRedocUiOptions,
    resolveRedocAsset,
} from "@suaveplan/api-openapi-ui-redoc";

const html = renderRedocShell({
    options: parseRedocUiOptions({ openapiUrl: "/openapi.json" }),
    resolvedAsset: resolveRedocAsset({ strategy: "cdn" }),
});

Usage: Advanced

Pre-render the shell for a multi-tenant host that picks up the OpenAPI URL from the request path:

import { renderRedocShell } from "@suaveplan/api-openapi-ui-redoc/html";

const options = parseRedocUiOptions({ openapiUrl: "/openapi.json", theme: "dark" });
const resolvedAsset = resolveRedocAsset({ strategy: "cdn" });

function htmlForTenant(tenant: string): string {
    return renderRedocShell({
        options,
        resolvedAsset,
        openapiUrlOverride: `/${tenant}/openapi.json`,
    });
}

API Reference

Symbol	Kind	Description
`RenderRedocShellInput`	type	`{ options, resolvedAsset, openapiUrlOverride? }`
`renderRedocShell`	fn	Render the HTML shell as a string

Implementation Notes

The escape function covers the five HTML special characters (&, <, >, ", ') plus the apostrophe — the same surface as the WHATWG HTML serialization-attribute rules. The JSON island is serialised via JSON.stringify and HTML-escaped so embedded </script> sequences in option values cannot escape the <script> context. The shell's bottom-of- body initialiser calls window.Redoc.init when the runtime defines it, falling back gracefully when the runtime is unavailable (e.g. during DOM unit tests that don't load the standalone bundle).

2.9 KiB Raw Blame History

html/render-shell — ReDoc HTML shell renderer