first commit

docs/api-stack/api/api-openapi-ui-swagger/src/handler/handler.md

@@ -0,0 +1,67 @@
+# `handler.ts` — `createSwaggerUiHandler` factory
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module exposes the primary entry point of `@suaveplan/api-openapi-ui-swagger`: a factory that returns an HTTP handler serving the Swagger UI HTML shell. The factory composes three earlier modules — options validation, asset resolution, and HTML rendering — into a single call site that the host's router can mount under `/docs/ui/swagger`.
+
+Construction is eager: validation, asset resolution, and shell rendering all happen at factory-call time. The returned handler is therefore an O(1) lookup that returns a pre-baked response. That puts all the failure modes (`INVALID_OPTIONS`, `ASSETS_MISSING`) at boot, where operators see them, never at first request.
+
+## Features
+
+- `createSwaggerUiHandler({ openapiUrl, ...options })` — returns a `SwaggerUiHandler`.
+- `createSwaggerUiHandlerArtifacts(...)` — handler plus parsed options for hosts that want introspection.
+- Strict response headers: `Content-Type: text/html; charset=utf-8`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`.
+- Pure handler — identical bytes returned on every call (no per-request work).
+- Eager validation at boot time.
+
+## Usage: Basic
+
+```ts
+import { createSwaggerUiHandler } from "@suaveplan/api-openapi-ui-swagger/handler";
+
+const handler = createSwaggerUiHandler({ openapiUrl: "/openapi.json" });
+const response = handler();
+// response.status === 200; response.body is the rendered HTML
+```
+
+## Usage: Advanced
+
+```ts
+import { createSwaggerUiHandlerArtifacts } from "@suaveplan/api-openapi-ui-swagger/handler";
+
+const { handler, options } = createSwaggerUiHandlerArtifacts({
+    openapiUrl: "/openapi.json",
+    title: "Acme — Customer API",
+    theme: "dark",
+    tryItOutEnabled: false,
+    uiAssets: "bundled",
+    assetBasePath: "/docs/ui/swagger/assets",
+});
+
+// `options` is the parsed, defaults-applied record; host can log it.
+console.log("[swagger-ui] mounted", options.title, options.uiAssets);
+
+// `handler` is a pure function — call it from every route adapter.
+const res = handler();
+void res;
+```
+
+## API Reference
+
+- `interface CreateSwaggerUiHandlerInput extends SwaggerUiOptionsInput { openapiUrl: string; assetBasePath?: string }`.
+- `interface SwaggerUiResponse { status; headers; body }`.
+- `type SwaggerUiHandler = () => SwaggerUiResponse`.
+- `createSwaggerUiHandler(input): SwaggerUiHandler`.
+- `createSwaggerUiHandlerArtifacts(input): { handler; options; openapiUrl }`.
+
+## Implementation Notes
+
+The factory is eager by design. The alternative — lazy validation per request — would let operators ship misconfigured handlers that look healthy until a doc-fetch arrives. The package picks reliability over latency: a single render per handler at boot.
+
+`assetBasePath` is required when `uiAssets = "bundled"`; omitting it raises `OPENAPI_UI_SWAGGER.ASSETS_MISSING` via `resolveAssets`. The factory does not infer a base path because the host owns the asset-route mount point — guessing would create cross-host inconsistency.
+
+The returned `SwaggerUiResponse` is an adapter-agnostic record. Hosts running on Hono call `c.html(body, status, headers)`; hosts on the in-memory router pass the record straight back; hosts on Node's `http` write `(status, headers, body)` directly. Avoiding `Response` keeps the package universal.