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