skills/docs/api-stack/api/api-openapi-ui-swagger

@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.

Documentation tree

• assets — This module owns the asset-resolution policy for the Swagger UI shell. The shell needs two payloads at boot — the upstr…
  • assets — This module owns the asset-resolution policy for the Swagger UI shell. The shell needs two payloads at boot — the upstr…
• error-codes — This module owns the stable error-code registry for @suaveplan/api-openapi-ui-swagger. Every public failure path rais…
  • error-codes — This module owns the stable error-code registry for @suaveplan/api-openapi-ui-swagger. Every public failure path rais…
• handler — This module exposes the primary entry point of @suaveplan/api-openapi-ui-swagger: a factory that returns an HTTP hand…
  • handler — This module exposes the primary entry point of @suaveplan/api-openapi-ui-swagger: a factory that returns an HTTP hand…
• html — This module produces the deterministic HTML payload returned by createSwaggerUiHandler. It accepts the OpenAPI docume…
  • render-shell — This module produces the deterministic HTML payload returned by createSwaggerUiHandler. It accepts the OpenAPI docume…
• options — This module owns the operator-facing options surface for @suaveplan/api-openapi-ui-swagger. It defines `swaggerUiOpti…
  • options — This module owns the operator-facing options surface for @suaveplan/api-openapi-ui-swagger. It defines `swaggerUiOpti…
• per-plugin — This module exposes the per-plugin variant of the Swagger UI handler. The host's /docs/{plugin} route serves a UI sco…
  • per-plugin — This module exposes the per-plugin variant of the Swagger UI handler. The host's /docs/{plugin} route serves a UI sco…

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

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

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.