84 lines
5.2 KiB
Markdown
84 lines
5.2 KiB
Markdown
# @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
|
|
|