Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# @suaveplan/api-openapi-ui-swagger — Swagger UI adapter for the `/docs/ui/swagger` endpoint of the Suaveplan API plugin system. Exposes createSwaggerUiHandler / createPerPluginSwaggerUiHandler — pure HTTP-handler factories returning a text/html shell pointing at the host's OpenAPI document and bootstrapping the real swagger-ui-dist runtime (CDN or bundled). Zod-validated SwaggerUiOptions (tryItOutEnabled, deepLinking, displayRequestDuration, filter, theme), stable OPENAPI_UI_SWAGGER.* error-code registry (ASSETS_MISSING, INVALID_OPTIONS), and sibling-shaped to api-openapi-ui-scalar so api-host can pick a UI uniformly.
|
||||
|
||||
Swagger UI adapter for the `/docs/ui/swagger` endpoint of the Suaveplan API plugin system (Stage 8.8). Returns a pure HTTP handler whose response is a `text/html` Swagger UI shell pointing at the host's OpenAPI document and bootstrapping the upstream `swagger-ui-dist` runtime — from the documented CDN by default, or from a host-bundled asset pipeline when operators opt in.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [assets](./src/assets/assets.md) — This module owns the asset-resolution policy for the Swagger UI shell. The shell needs two payloads at boot — the upstr…
|
||||
- [assets](./src/assets/assets.md) — This module owns the asset-resolution policy for the Swagger UI shell. The shell needs two payloads at boot — the upstr…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-openapi-ui-swagger`. Every public failure path rais…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-openapi-ui-swagger`. Every public failure path rais…
|
||||
- [handler](./src/handler/handler.md) — This module exposes the primary entry point of `@suaveplan/api-openapi-ui-swagger`: a factory that returns an HTTP hand…
|
||||
- [handler](./src/handler/handler.md) — This module exposes the primary entry point of `@suaveplan/api-openapi-ui-swagger`: a factory that returns an HTTP hand…
|
||||
- [html](./src/html/render-shell.md) — This module produces the deterministic HTML payload returned by `createSwaggerUiHandler`. It accepts the OpenAPI docume…
|
||||
- [render-shell](./src/html/render-shell.md) — This module produces the deterministic HTML payload returned by `createSwaggerUiHandler`. It accepts the OpenAPI docume…
|
||||
- [options](./src/options/options.md) — This module owns the operator-facing options surface for `@suaveplan/api-openapi-ui-swagger`. It defines `swaggerUiOpti…
|
||||
- [options](./src/options/options.md) — This module owns the operator-facing options surface for `@suaveplan/api-openapi-ui-swagger`. It defines `swaggerUiOpti…
|
||||
- [per-plugin](./src/per-plugin/per-plugin.md) — This module exposes the per-plugin variant of the Swagger UI handler. The host's `/docs/{plugin}` route serves a UI sco…
|
||||
- [per-plugin](./src/per-plugin/per-plugin.md) — This module exposes the per-plugin variant of the Swagger UI handler. The host's `/docs/{plugin}` route serves a UI sco…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Why
|
||||
|
||||
`/docs/ui/swagger` is one of the pluggable UI choices for The OpenAPI surface. Operators familiar with Swagger's interactive try-it-out shell keep that surface by selecting this adapter in `host.openapi.ui = "swagger"`. The package matches the shape of the sibling Scalar adapter so the host's selection logic remains uniform across UI choices.
|
||||
|
||||
## Modules
|
||||
|
||||
- `handler/` — `createSwaggerUiHandler` and `createSwaggerUiHandlerArtifacts`. Eager-validating factory that returns a pure HTTP handler.
|
||||
- `per-plugin/` — `createPerPluginSwaggerUiHandler` for the `/docs/{plugin}` filtered view.
|
||||
- `options/` — Zod-validated `SwaggerUiOptions` (`title`, `tryItOutEnabled`, `deepLinking`, `displayRequestDuration`, `filter`, `theme`, `uiAssets`, `version`).
|
||||
- `assets/` — CDN vs bundled asset resolution; embedded asset registry; ASSETS_MISSING strict-mode guarantee.
|
||||
- `html/` — deterministic HTML shell renderer with break-out-safe JSON config island.
|
||||
- `error-codes/` — `OPENAPI_UI_SWAGGER.*` registry (`ASSETS_MISSING`, `INVALID_OPTIONS`).
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
import { createSwaggerUiHandler } from "@suaveplan/api-openapi-ui-swagger";
|
||||
|
||||
const handler = createSwaggerUiHandler({
|
||||
openapiUrl: "/openapi.json",
|
||||
title: "Acme — Customer API",
|
||||
tryItOutEnabled: true,
|
||||
});
|
||||
|
||||
// Hono / worker bridge / in-memory router — call handler() and
|
||||
// translate the SwaggerUiResponse into the adapter's native Response.
|
||||
const res = handler();
|
||||
console.log(res.headers["Content-Type"]); // text/html; charset=utf-8
|
||||
```
|
||||
|
||||
## Bundled assets
|
||||
|
||||
```ts
|
||||
import {
|
||||
createSwaggerUiHandler,
|
||||
listBundledAssetNames,
|
||||
readBundledAsset,
|
||||
} from "@suaveplan/api-openapi-ui-swagger";
|
||||
|
||||
const handler = createSwaggerUiHandler({
|
||||
openapiUrl: "/openapi.json",
|
||||
uiAssets: "bundled",
|
||||
assetBasePath: "/docs/ui/swagger/assets",
|
||||
});
|
||||
|
||||
// Host mounts an asset route — serves the bundled bytes by name.
|
||||
for (const name of listBundledAssetNames()) {
|
||||
const bytes = readBundledAsset(name);
|
||||
// host.serve(`/docs/ui/swagger/assets/${name}`, bytes)
|
||||
void bytes;
|
||||
}
|
||||
```
|
||||
|
||||
## Error codes
|
||||
|
||||
- `OPENAPI_UI_SWAGGER.INVALID_OPTIONS` — caller-supplied options failed Zod validation.
|
||||
- `OPENAPI_UI_SWAGGER.ASSETS_MISSING` — bundled mode requested without `assetBasePath`, or a bundled asset name is not registered.
|
||||
|
||||
Both surfaces raise at factory-call time (eager validation), so misconfiguration is caught at boot rather than at first request.
|
||||
|
||||
Reference in New Issue
Block a user