first commit
This commit is contained in:
83
docs/api-stack/api/api-openapi-ui-redoc/README.md
Normal file
83
docs/api-stack/api/api-openapi-ui-redoc/README.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# @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
|
||||
|
||||
Reference in New Issue
Block a user