skills/docs/api-stack/api/api-openapi-ui-redoc/README.md

@suaveplan/api-openapi-ui-redoc — ReDoc UI adapter for the Suaveplan api-host. Mounts the ReDoc HTML shell at /docs/ui/redoc (or any caller-chosen path) via createRedocUiHandler({ openapiUrl, title, theme, expandResponses }) and at /docs/{plugin}/ui/redoc via createPerPluginRedocUiHandler. Validates RedocUiOptions through a strict Zod schema, resolves the ReDoc runtime bundle from a cdn / bundled / inline strategy, embeds the configured options into the shell as a JSON island, and raises the OPENAPI_UI_REDOC_* error-code family on collision, missing asset, or invalid options. Structural sibling of api-graphql-ui-altair and api-graphql-ui-graphiql.

Stage-8 ReDoc UI adapter for the Suaveplan api-host. Mounts the ReDoc HTML shell at /docs/ui/redoc (or any caller-chosen path) via createRedocUiHandler and at /docs/{plugin}/ui/redoc via createPerPluginRedocUiHandler. Validates options through a strict Zod schema, resolves the runtime bundle from a cdn / bundled / inline strategy, and raises the OPENAPI_UI_REDOC_* error-code family on missing assets or invalid options.

Structural sibling of @suaveplan/api-graphql-ui-altair and @suaveplan/api-graphql-ui-graphiql.

Documentation tree

• assets — This module resolves the runtime asset URL the ReDoc HTML shell references. The package supports three asset strategies…
  • assets — This module resolves the runtime asset URL the ReDoc HTML shell references. The package supports three asset strategies…
• error-codes — This module defines the frozen error-code namespace shared by the ReDoc UI adapter. Every fault the package raises carr…
  • error-codes — This module defines the frozen error-code namespace shared by the ReDoc UI adapter. Every fault the package raises carr…
• handler — This module exposes createRedocUiHandler, the factory the api-host calls to obtain the HTTP handler serving the ReDoc…
  • handler — This module exposes createRedocUiHandler, the factory the api-host calls to obtain the HTTP handler serving the ReDoc…
• html — This module exposes renderRedocShell, the pure function that produces the ReDoc HTML shell consumed by both the globa…
  • render-shell — This module exposes renderRedocShell, the pure function that produces the ReDoc HTML shell consumed by both the globa…
• options — This module defines the Zod schema and parser for RedocUiOptions, the configuration bundle the ReDoc UI handler accep…
  • options — This module defines the Zod schema and parser for RedocUiOptions, the configuration bundle the ReDoc UI handler accep…
• per-plugin — This module exposes createPerPluginRedocUiHandler, the sibling of createRedocUiHandler for hosts that mount per-plu…
  • per-plugin — This module exposes createPerPluginRedocUiHandler, the sibling of createRedocUiHandler for hosts that mount per-plu…

Install

bun add @suaveplan/api-openapi-ui-redoc

Quick start

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

const handler = createRedocUiHandler({
    openapiUrl: "/openapi.json",
    title: "Acme API",
    theme: "dark",
    expandResponses: "200,201",
});

const res = handler();
// res.body is the rendered HTML shell, ready to send.

Modules

Module	Subpath	Description
handler/handler.ts	@suaveplan/api-openapi-ui-redoc/handler	createRedocUiHandler + RedocHttpResponse
per-plugin/per-plugin.ts	@suaveplan/api-openapi-ui-redoc/per-plugin	createPerPluginRedocUiHandler
options/options.ts	@suaveplan/api-openapi-ui-redoc/options	RedocUiOptions Zod schema + parser
assets/assets.ts	@suaveplan/api-openapi-ui-redoc/assets	cdn / bundled / inline strategy resolver
html/render-shell.ts	@suaveplan/api-openapi-ui-redoc/html	Pure HTML shell renderer
error-codes/error-codes.ts	@suaveplan/api-openapi-ui-redoc/error-codes	OPENAPI_UI_REDOC_* registry

Asset strategies

• cdn (default) — point the shell at the canonical Redocly CDN URL (https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js). Zero-byte deploy; one network round-trip per first-paint.
• bundled — operators supply the runtime bytes; the package serves them from a cache-busted local URL.
• inline — embed the runtime body directly into the HTML shell. One network round-trip total, at the cost of a larger first-paint payload.

Error codes

• OPENAPI_UI_REDOC_ASSETS_MISSING — bundled or inline mode requested without a payload.
• OPENAPI_UI_REDOC_INVALID_OPTIONS — Zod rejected the option bundle.

License

MIT