suaveplan/openspec/archive/2026-05-26-api-openapi-ui-redoc/proposal.md

@suaveplan/api-openapi-ui-redoc — ReDoc UI adapter for the /docs endpoint

Package: @suaveplan/api-openapi-ui-redoc Status: PROPOSED Type: new-package Stage: 8 — see umbrella openspec/changes/api-plugin-foundation/

Why

Per design doc §7, ReDoc is the third pluggable UI choice for /docs. ReDoc's three-pane layout suits read-heavy API reference sites. The package mirrors the Scalar / Swagger sibling shapes so the host's UI selection logic is uniform.

What changes

• ADDED: createRedocUiHandler({ openapiUrl, title, theme, expandResponses }) — returns an HTTP handler serving the ReDoc HTML shell pointing at openapiUrl.
• ADDED: createPerPluginRedocUiHandler({ openapiUrlForPlugin, plugin }) — for /docs/{plugin}.
• ADDED: RedocUiOptions Zod schema (theme, expandResponses, hideDownloadButton, nativeScrollbars).
• ADDED: Asset strategy (cdn / bundled) mirroring the Scalar adapter.
• ADDED: Error codes (OPENAPI_UI_REDOC_*): ASSETS_MISSING, INVALID_OPTIONS.

Out of scope

• Authoring OpenAPI documents — that's api-openapi.
• Scalar / Swagger — sibling packages.

Source mapping

Genesis-original. Source of design intent: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md.

Requirement	Design doc section
Pluggable UI (ReDoc as alternative)	§7

Verification approach

• src/handler/handler.test.ts — HTML references openapiUrl; expandResponses toggles the ReDoc config.
• src/per-plugin/per-plugin.test.ts — per-plugin URL embedded.
• src/assets/assets.test.ts — cdn vs bundled.
• tests/dep-graph.test.ts — runtime deps.

Migration impact

None — additive only. api-host selects this when host.openapi.ui = "redoc".