`handler.ts` — `createSwaggerUiHandler` factory

(no submodules)

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

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

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.

3.3 KiB Raw Blame History

handler.ts — createSwaggerUiHandler factory