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

@suaveplan/api-openapi — OpenAPI 3.1 document emitter

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

Why

Plugins author routes with Zod schemas (design doc §7). The API host needs to emit a single merged OpenAPI 3.1 document combining every plugin's routes, every manifest's metadata, the active auth adapter's securitySchemes, and host-level info. Without this, plugin authors would each write hand-maintained OpenAPI documents that drift from runtime behaviour. Auto-emitting from the Zod contract is the only sustainable answer.

What changes

• ADDED: createOpenapiEmitter({ manifests, routes, authAdapter, hostConfig }) — reads each plugin's manifest (name, displayName, description, scopes, route prefix, publicRoutes), every registered route's Zod schemas, the active auth adapter's securitySchemes, and host.json (server URLs, contact, license). Returns a OpenapiEmitter with getJson() and getYaml().
• ADDED: Zod-to-OpenAPI conversion via @asteasolutions/zod-to-openapi — established, OpenAPI 3.1, handles refs / discriminators / coercion. Plugins import z from zod directly (genesis convention).
• ADDED: Namespacing rules — tags from plugin displayName; components/schemas prefixed (billing.Invoice); operationId = <pluginName>.<method>.<routePath>; security inherited from the active auth adapter except on publicRoutes.
• ADDED: HTTP endpoints (mounted by the host): GET /openapi.json, GET /openapi.yaml, GET /docs, GET /docs/{plugin} (per-plugin filtered view).
• ADDED: openapi.generation capability — optional. A plugin opts in by declaring openapi.contributes = true. Plugins NOT opting in still get their routes documented unless openapi: false is per-route.
• ADDED: host.openapi.strictness ("warn" | "refuse-install") — when a route is missing a request/response schema, the emitter either logs a warning or the host refuses to install the plugin. Defaults to "warn" in dev, "refuse-install" in production.
• ADDED: Error codes (OPENAPI_*): MISSING_SCHEMA, SCHEMA_CONVERSION_FAILED, OPERATION_ID_COLLISION, UNKNOWN_PLUGIN_IN_FILTER.

Out of scope

• The UI itself — Scalar / Swagger / ReDoc each ship in their own sibling package.
• Authoring OpenAPI by hand — plugins MUST use Zod.
• Generating client SDKs from the emitted document — separate change.

Source mapping

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

Requirement	Design doc section
Auto-emit OpenAPI 3.1 from Zod	§7
Endpoints /openapi.json, /openapi.yaml, /docs, /docs/{plugin}	§7
Namespacing rules	§7
host.openapi.strictness for missing schemas	§7 (this proposal locks the policy)

Verification approach

• src/emitter/emitter.test.ts — full emission against a fixture manifest + route set; assert tags, components, operationIds, security all correct.
• src/emitter/emitter.spec-conformance.test.ts — strictness modes (warn logs but emits; refuse-install raises OPENAPI_MISSING_SCHEMA).
• src/endpoints/endpoints.test.ts — every endpoint returns the right Content-Type and body shape (json vs yaml; filtered view excludes other plugins).
• src/namespacing/namespacing.test.ts — operationId determinism + collision detection.
• tests/dep-graph.test.ts — runtime deps (api-types, error, logger, zod, @asteasolutions/zod-to-openapi).

Migration impact

None — additive only. The host mounts the OpenAPI endpoints when this package is installed.