# @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`.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

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

## Quick start

```ts
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