suaveplan/openspec/archive/2026-05-26-api-openapi-ui-swagger/proposal.md

@suaveplan/api-openapi-ui-swagger — Swagger UI adapter for the /docs endpoint

Package: @suaveplan/api-openapi-ui-swagger Status: PROPOSED Type: new-package Stage: 8 — see umbrella openspec/changes/api-plugin-foundation/

Why

Per design doc §7, Swagger UI is one of the pluggable UI choices for /docs. Many operators prefer Swagger UI for its familiar interactive try-it-out surface. Wrapping it in a sibling package matching api-openapi-ui-scalar's shape keeps the host's selection logic uniform.

What changes

• ADDED: createSwaggerUiHandler({ openapiUrl, title, tryItOutEnabled }) — returns an HTTP handler serving the Swagger UI HTML shell.
• ADDED: createPerPluginSwaggerUiHandler({ openapiUrlForPlugin, plugin }) — for /docs/{plugin}.
• ADDED: SwaggerUiOptions Zod schema (tryItOutEnabled, deepLinking, displayRequestDuration, filter, theme).
• ADDED: Asset strategy (cdn / bundled) mirroring the Scalar adapter.
• ADDED: Error codes (OPENAPI_UI_SWAGGER_*): ASSETS_MISSING, INVALID_OPTIONS.

Out of scope

• Authoring OpenAPI documents — that's api-openapi.
• Scalar / ReDoc — sibling packages.

Source mapping

Genesis-original. Source of design intent: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md.

Requirement	Design doc section
Pluggable UI (Swagger as alternative)	§7

Verification approach

• src/handler/handler.test.ts — handler returns HTML referencing openapiUrl; tryItOutEnabled toggles the Swagger config flag.
• src/per-plugin/per-plugin.test.ts — per-plugin URL embedded.
• src/assets/assets.test.ts — cdn vs bundled resolution.
• tests/dep-graph.test.ts — runtime deps include api-types, error, zod, the Swagger UI runtime.

Migration impact

None — additive only. api-host selects this when host.openapi.ui = "swagger".