@znight/openapi 0.0.0-stage → 0.1.0

package/src/emit/index.ts

@@ -0,0 +1,377 @@
+/**
+ * `@znight/openapi/emit`: writes `openapi.json` (or YAML) at build time (§7.5 of RFC 0002), for
+ * `znight openapi`, `znight build --openapi` and the `openapi()` Vite plugin.
+ *
+ * 1. the compiler options are resolved like `znight generate` does (`znight.config.*`, else the
+ *    `znight()` plugin of the Vite config);
+ * 2. `compile()` in `serve` mode: errors stop everything before any module runs;
+ * 3. a **child process** loads the generated module (Bun: the compiler preload; Node.js: a Vite
+ *    server in middleware mode) and runs `buildOpenApiDocument`;
+ * 4. each output is written atomically, only when it changed; a checked output (`check`) is never
+ *    written: when it is missing or stale, it is reported.
+ */
+import type { Diagnostic } from '@znight/compiler'
+import type { OpenApiWarning } from '../build.ts'
+import type { OpenApiObject } from '../types.ts'
+import type { ChildPayload, ChildResult } from './protocol.ts'
+
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { ErrorCode, ZnightError } from '@znight/core'
+
+import { toYaml } from '../openapi.ts'
+
+/** Runtime loading the application modules: `'auto'` is the runtime running the caller. */
+export type EmitRuntime = 'auto' | 'node' | 'bun'
+
+/** Options of {@link emitOpenApi}. */
+export interface EmitOpenApiOptions {
+  /** Project root. Default `process.cwd()`. */
+  readonly root?: string
+  /** Output files, relative to `root`; `.yaml` / `.yml` write YAML (optional peer `yaml`). Default `'openapi.json'`. */
+  readonly output?: string | readonly string[]
+  /**
+   * Never write: report missing or stale outputs (`stale`, `staleFiles`). `true` checks every output;
+   * a list checks only these outputs (relative to `root`, each one an `output`) and writes the others
+   * as usual (the `openapi()` Vite plugin checks the committed file and writes the build output).
+   */
+  readonly check?: boolean | readonly string[]
+  /** The HTTP prefix: `servers` defaults to `[{ url: prefix }]` when `@OpenApiDocument` declares none. */
+  readonly prefix?: string
+  /** Default `'auto'`. */
+  readonly runtime?: EmitRuntime
+  /** Module (relative to `root`) whose default export is a `SchemaConverter[]`. */
+  readonly converters?: string
+  /** Vite config file (default: `vite.config.*` of the root). */
+  readonly config?: string
+  /** How Vite loads its config (`bundle`, `runner`, `native`). */
+  readonly configLoader?: string
+  /**
+   * The compiler options, already resolved (the CLI and the Vite plugin pass theirs). Default:
+   * `znight.config.*`, else the options of the `znight()` plugin of the Vite config.
+   */
+  readonly compilerOptions?: Readonly<Record<string, unknown>>
+  /** Environment of the child process. Default `process.env`, with `NODE_ENV` defaulting to `production`. */
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+/** Result of {@link emitOpenApi}. */
+export interface EmitOpenApiResult {
+  /** `false` when the compile failed (see `diagnostics`): nothing ran and nothing was written. */
+  readonly ok: boolean
+  /** Outputs written (absolute paths); never a checked output. */
+  readonly written: readonly string[]
+  /** `check`: a checked output is missing or differs (listed in `staleFiles`). */
+  readonly stale: boolean
+  readonly staleFiles: readonly string[]
+  /** The document (`undefined` when the compile failed). */
+  readonly document: OpenApiObject | undefined
+  /** Compiler diagnostics (warnings included). */
+  readonly diagnostics: readonly Diagnostic[]
+  /** Warnings of the assembly (`unrepresentable: 'warn'`...). */
+  readonly warnings: readonly OpenApiWarning[]
+  /** Absolute paths of the outputs. */
+  readonly outputs: readonly string[]
+  readonly runtime: 'node' | 'bun'
+}
+
+interface CompilerModule {
+  compile(options: Record<string, unknown>): Promise<{
+    readonly ok: boolean
+    readonly diagnostics: readonly Diagnostic[]
+    readonly outFile: string
+  }>
+  loadZnightConfig?(cwd: string): Promise<{ file: string | undefined; options: Record<string, unknown> }>
+}
+
+const VITE_CONFIGS = [
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.ts',
+  'vite.config.cjs',
+  'vite.config.mts',
+  'vite.config.cts',
+]
+
+/** Compiles the application and writes (or checks) its OpenAPI document. */
+export async function emitOpenApi(options: EmitOpenApiOptions = {}): Promise<EmitOpenApiResult> {
+  const root = resolve(options.root ?? process.cwd())
+  const outputs = (typeof options.output === 'string' ? [options.output] : (options.output ?? ['openapi.json'])).map(
+    file => resolve(root, file),
+  )
+  const checked = checkedOutputs(root, outputs, options.check)
+  const runtime = resolveRuntime(options.runtime ?? 'auto')
+  const compiler = (await importFromProject(root, '@znight/compiler')) as CompilerModule
+  const viteConfig = findViteConfig(root, options.config)
+  const compilerOptions =
+    options.compilerOptions ?? (await resolveCompilerOptions(root, compiler, viteConfig, options.configLoader))
+  const compiled = await compiler.compile({
+    ...compilerOptions,
+    root: resolve(root, String(compilerOptions['root'] ?? '.')),
+    mode: 'serve',
+  })
+  const base = { outputs, runtime, diagnostics: compiled.diagnostics }
+  if (!compiled.ok) {
+    return { ...base, ok: false, written: [], stale: false, staleFiles: [], document: undefined, warnings: [] }
+  }
+  const converters = options.converters === undefined ? undefined : resolve(root, options.converters)
+  if (converters !== undefined && !existsSync(converters)) {
+    throw new ZnightError(
+      ErrorCode.InvalidOpenApiDefinition,
+      `The converters module ${options.converters} does not exist`,
+    )
+  }
+  const result = await runChild(
+    {
+      root,
+      runtime,
+      outFile: compiled.outFile,
+      viteConfig: viteConfig ?? false,
+      ...(options.configLoader === undefined ? {} : { configLoader: options.configLoader }),
+      compilerOptions: jsonOnly(compilerOptions),
+      ...(converters === undefined ? {} : { converters }),
+      ...(options.prefix === undefined ? {} : { prefix: options.prefix }),
+    },
+    options.env ?? process.env,
+  )
+  if (!result.ok) {
+    const code =
+      Object.values(ErrorCode).find(candidate => candidate === result.error.code) ?? ErrorCode.SchemaConversionFailed
+    const message = result.error.message.replace(/^ZNIGHT\d{3}: /, '')
+    throw new ZnightError(code, message, { hints: result.error.hints })
+  }
+  const document = JSON.parse(result.json) as OpenApiObject
+  const contents = new Map<string, string>()
+  for (const output of outputs) {
+    contents.set(output, /\.ya?ml$/i.test(output) ? await toYaml(document) : result.json)
+  }
+  const changed = outputs.filter(output => readText(output) !== contents.get(output))
+  const staleFiles = changed.filter(output => checked.has(output))
+  const written: string[] = []
+  for (const output of changed) {
+    if (checked.has(output)) continue
+    writeAtomically(output, contents.get(output) ?? '')
+    written.push(output)
+  }
+  return {
+    ...base,
+    ok: true,
+    written,
+    stale: staleFiles.length > 0,
+    staleFiles,
+    document,
+    warnings: result.warnings,
+  }
+}
+
+/** The outputs that `check` checks (absolute paths). */
+function checkedOutputs(
+  root: string,
+  outputs: readonly string[],
+  check: EmitOpenApiOptions['check'],
+): ReadonlySet<string> {
+  if (check === undefined || check === false) return new Set()
+  if (check === true) return new Set(outputs)
+  const checked = new Set(check.map(file => resolve(root, file)))
+  const unknown = check.filter(file => !outputs.includes(resolve(root, file)))
+  if (unknown.length > 0) {
+    throw new ZnightError(
+      ErrorCode.InvalidOpenApiDefinition,
+      `check lists ${unknown.join(', ')}, which ${unknown.length > 1 ? 'are not outputs' : 'is not an output'}`,
+      { hints: ['check: true checks every output; a list names outputs (relative to the root)'] },
+    )
+  }
+  return checked
+}
+
+function resolveRuntime(runtime: EmitRuntime): 'node' | 'bun' {
+  if (runtime === 'node' || runtime === 'bun') return runtime
+  return process.versions['bun'] === undefined ? 'node' : 'bun'
+}
+
+/** The Vite config file of the project, if any. */
+export function findViteConfig(root: string, config?: string): string | undefined {
+  if (config !== undefined) return resolve(root, config)
+  return VITE_CONFIGS.map(file => join(root, file)).find(file => existsSync(file))
+}
+
+async function resolveCompilerOptions(
+  root: string,
+  compiler: CompilerModule,
+  viteConfig: string | undefined,
+  configLoader: string | undefined,
+): Promise<Record<string, unknown>> {
+  const config = await compiler.loadZnightConfig?.(root)
+  if (config?.file !== undefined) {
+    const { logLevel: _logLevel, ...rest } = config.options
+    return { ...rest, root: resolve(root, String(rest['root'] ?? '.')) }
+  }
+  if (viteConfig === undefined) return { root }
+  const vite = (await importFromProject(root, 'vite')) as {
+    resolveConfig?(
+      config: Record<string, unknown>,
+      command: string,
+      mode?: string,
+      env?: string,
+    ): Promise<{ plugins: readonly unknown[]; root: string }>
+  }
+  if (typeof vite.resolveConfig !== 'function') return { root }
+  const nodeEnv = process.env['NODE_ENV']
+  let resolved: { plugins: readonly unknown[]; root: string }
+  try {
+    resolved = await vite.resolveConfig(
+      {
+        configFile: viteConfig,
+        root,
+        mode: 'production',
+        logLevel: 'silent',
+        ...(configLoader === undefined ? {} : { configLoader }),
+      },
+      'build',
+      'production',
+      'production',
+    )
+  } finally {
+    if (nodeEnv === undefined) delete process.env['NODE_ENV']
+    else process.env['NODE_ENV'] = nodeEnv
+  }
+  for (const plugin of resolved.plugins) {
+    const api = (plugin as { name?: unknown; api?: { options?: unknown; compiler?: { options?: { root?: unknown } } } })
+      .api
+    if ((plugin as { name?: unknown }).name !== 'znight' || api === undefined) continue
+    const given =
+      typeof api.options === 'object' && api.options !== null ? (api.options as Record<string, unknown>) : {}
+    const compilerRoot = api.compiler?.options?.root
+    return {
+      ...given,
+      root: typeof compilerRoot === 'string' ? compilerRoot : resolve(resolved.root, String(given['root'] ?? '.')),
+    }
+  }
+  return { root }
+}
+
+async function importFromProject(root: string, specifier: string): Promise<unknown> {
+  let resolved: string | undefined
+  try {
+    resolved = createRequire(join(root, 'package.json')).resolve(specifier)
+  } catch {
+    resolved = undefined
+  }
+  try {
+    return await import(resolved === undefined ? specifier : pathToFileURL(resolved).href)
+  } catch (error) {
+    throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, `Cannot load ${specifier}`, {
+      cause: error,
+      hints: [`Install it in the project: npm install -D ${specifier}`],
+    })
+  }
+}
+
+/** The JSON-compatible part of the compiler options (sent to the child process). */
+function jsonOnly(options: Readonly<Record<string, unknown>>): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(options)) {
+    try {
+      const json = JSON.stringify(value)
+      if (json !== undefined && JSON.stringify(JSON.parse(json)) === json && typeof value !== 'function') {
+        result[key] = JSON.parse(json)
+      }
+    } catch {
+      // functions, extension objects: the child reads znight.config.* itself
+    }
+  }
+  return result
+}
+
+/** The script of the child process (source or built). */
+function childScript(): { file: string; source: boolean } {
+  const source = import.meta.url.endsWith('.ts')
+  return { file: fileURLToPath(new URL(source ? './child.ts' : './emit-child.mjs', import.meta.url)), source }
+}
+
+function runChild(
+  payload: Omit<ChildPayload, 'result'>,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<ChildResult> {
+  const directory = mkdtempSync(join(tmpdir(), 'znight-openapi-emit-'))
+  const payloadFile = join(directory, 'payload.json')
+  const resultFile = join(directory, 'result.json')
+  const script = childScript()
+  writeFileSync(
+    payloadFile,
+    JSON.stringify({
+      ...payload,
+      ...(script.source ? { sourceConditions: true } : {}),
+      result: resultFile,
+    } satisfies ChildPayload),
+  )
+  const bun = process.versions['bun'] !== undefined
+  let executable: string
+  if (payload.runtime === 'bun') executable = bun ? process.execPath : 'bun'
+  else executable = bun ? 'node' : process.execPath
+  const args = [...(script.source ? ['--conditions=@znight/source'] : []), script.file, payloadFile]
+  const childEnv: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) if (value !== undefined) childEnv[key] = value
+  childEnv['NODE_ENV'] ??= 'production'
+  return new Promise<ChildResult>((resolvePromise, reject) => {
+    const child = spawn(executable, args, { cwd: payload.root, env: childEnv, stdio: ['ignore', 'pipe', 'pipe'] })
+    let output = ''
+    child.stdout?.on('data', (chunk: Buffer) => {
+      output += chunk.toString()
+    })
+    child.stderr?.on('data', (chunk: Buffer) => {
+      output += chunk.toString()
+    })
+    child.on('error', error => {
+      rmSync(directory, { recursive: true, force: true })
+      reject(
+        new ZnightError(
+          ErrorCode.InvalidOpenApiDefinition,
+          `Cannot start ${executable} to load the application modules`,
+          {
+            cause: error,
+            hints: [
+              payload.runtime === 'bun'
+                ? 'Install Bun, or use --runtime node'
+                : 'Install Node.js 24, or use --runtime bun',
+            ],
+          },
+        ),
+      )
+    })
+    child.on('close', code => {
+      const text = readText(resultFile)
+      rmSync(directory, { recursive: true, force: true })
+      if (text === undefined) {
+        reject(
+          new ZnightError(
+            ErrorCode.InvalidOpenApiDefinition,
+            `Loading the application modules failed (${executable} exited with code ${String(code)})${output.trim() === '' ? '' : `:\n${output.trim()}`}`,
+          ),
+        )
+        return
+      }
+      resolvePromise(JSON.parse(text) as ChildResult)
+    })
+  })
+}
+
+function readText(file: string): string | undefined {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/** Writes through a temporary file and a rename (readers never see a partial file). */
+function writeAtomically(file: string, content: string): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const temporary = `${file}.${process.pid}.tmp`
+  writeFileSync(temporary, content)
+  renameSync(temporary, file)
+}

package/src/emit/protocol.ts

@@ -0,0 +1,35 @@
+/** Messages between `emitOpenApi()` and its child process (JSON files). */
+import type { OpenApiWarning } from '../build.ts'
+
+/** What the child process receives. */
+export interface ChildPayload {
+  readonly root: string
+  readonly runtime: 'node' | 'bun'
+  /** Absolute path of the generated module. */
+  readonly outFile: string
+  /** Vite config file (Node.js), `false` without one. */
+  readonly viteConfig: string | false
+  readonly configLoader?: string
+  /** JSON-compatible compiler options (used when the project has no `znight.config.*`). */
+  readonly compilerOptions: Readonly<Record<string, unknown>>
+  /** Absolute path of a module whose default export is a `SchemaConverter[]`. */
+  readonly converters?: string
+  readonly prefix?: string
+  /** The workspace runs from sources: resolve `@znight/*` packages with the `@znight/source` condition. */
+  readonly sourceConditions?: boolean
+  /** Where the child writes its {@link ChildResult}. */
+  readonly result: string
+}
+
+/** What the child process writes. */
+export type ChildResult =
+  | {
+      readonly ok: true
+      readonly json: string
+      readonly warnings: readonly OpenApiWarning[]
+      readonly stats: { readonly operations: number; readonly schemas: number; readonly durationMs: number }
+    }
+  | {
+      readonly ok: false
+      readonly error: { readonly code: string | undefined; readonly message: string; readonly hints: readonly string[] }
+    }

package/src/index.ts

@@ -0,0 +1,94 @@
+/**
+ * `@znight/openapi`: OpenAPI 3.1 documents built at compile time from the controllers of
+ * `@znight/http` (types, JSDoc, Standard Schemas, a few `@Api*` decorators), served with Scalar or
+ * Swagger UI by `OpenApiPlugin`, and emitted at build time (`znight openapi`).
+ */
+import './metadata.ts'
+
+export type {
+  OpenApiDocumentTemplate,
+  OpenApiMetadata,
+  OpenApiOperationDefinition,
+  OpenApiSchemaSlot,
+  OperationTemplate,
+  ParametersPlaceholder,
+  SchemaPlaceholder,
+  SchemaTemplate,
+} from './metadata.ts'
+export type {
+  ComponentsObject,
+  ContactObject,
+  EncodingObjectOf,
+  ExampleObject,
+  ExternalDocumentationObject,
+  HeaderObject,
+  HeaderObjectOf,
+  InfoObject,
+  JsonSchema,
+  JsonValue,
+  LicenseObject,
+  MediaTypeObject,
+  MediaTypeObjectOf,
+  OAuthFlowObject,
+  OAuthFlowsObject,
+  OpenApiMethod,
+  OpenApiObject,
+  OperationObject,
+  OperationObjectOf,
+  ParameterLocation,
+  ParameterObject,
+  ParameterObjectOf,
+  PathItemObject,
+  ReferenceObject,
+  RequestBodyObject,
+  RequestBodyObjectOf,
+  ResponseObject,
+  ResponseObjectOf,
+  SecurityRequirementObject,
+  SecuritySchemeObject,
+  ServerObject,
+  ServerVariableObject,
+  SpecificationExtensions,
+  TagObject,
+} from './types.ts'
+
+export {
+  type BuildOpenApiOptions,
+  buildOpenApiDocument,
+  type OpenApiBuildResult,
+  type OpenApiOperationView,
+  type OpenApiWarning,
+} from './build.ts'
+export {
+  BUILT_IN_CONVERTERS,
+  type SchemaConverter,
+  type SchemaConverterContext,
+  standardJsonSchemaConverter,
+  valibotConverter,
+} from './converters.ts'
+export {
+  ApiBody,
+  type ApiBodyOptions,
+  ApiExclude,
+  ApiHeader,
+  ApiOperation,
+  type ApiOperationOptions,
+  type ApiParameterOptions,
+  ApiQuery,
+  ApiResponse,
+  type ApiResponseOptions,
+  type ApiResponseStatus,
+  ApiSecurity,
+  ApiTags,
+  OpenApiDocument,
+  type OpenApiDocumentOptions,
+  type OperationIdStyle,
+  type SecurityDecision,
+  type SecurityRequirementInput,
+  type SecurityScheme,
+  securityScheme,
+} from './decorators.ts'
+export { OPENAPI_METADATA_VERSION } from './metadata.ts'
+export { OpenApi, OpenApiTokens } from './openapi.ts'
+export { OpenApiPlugin, type OpenApiPluginOptions, type OpenApiUiOption } from './plugin.ts'
+export { CDN_ORIGIN, UI_PACKAGES, type UiAsset, type UiKind, type UiPackage } from './ui.ts'

package/src/metadata.ts

@@ -0,0 +1,112 @@
+/**
+ * `metadata.extensions.openapi` (format 1): the contract between the compiler extension
+ * (`@znight/openapi/compiler`) and the runtime (`buildOpenApiDocument`, `OpenApiPlugin`).
+ *
+ * Everything is JSON-compatible, except the `schema` values of {@link OpenApiSchemaSlot}s (Standard
+ * Schemas imported by the generated module). Where a schema is expected, the compiler writes JSON
+ * Schema or a {@link SchemaPlaceholder} that the assembly replaces.
+ */
+import type { Token } from '@znight/core'
+import type { StandardSchemaV1 } from '@znight/http'
+import type {
+  ExternalDocumentationObject,
+  InfoObject,
+  JsonSchema,
+  JsonValue,
+  OpenApiMethod,
+  OperationObjectOf,
+  SecurityRequirementObject,
+  SecuritySchemeObject,
+  ServerObject,
+  TagObject,
+} from './types.ts'
+
+/** Format version of {@link OpenApiMetadata}. */
+export const OPENAPI_METADATA_VERSION = 1
+
+/** A Standard Schema converted at assembly: `{ $ref }` to its component once replaced. */
+export interface SchemaPlaceholder {
+  readonly $znight: 'schema'
+  /** Slot name ({@link OpenApiSchemaSlot.name}). */
+  readonly name: string
+  readonly io: 'input' | 'output'
+}
+
+/**
+ * In `parameters` arrays: one parameter per property of the (input) object schema of a slot
+ * (`@Query(SearchQuery)`), `required` from its `required` list.
+ */
+export interface ParametersPlaceholder {
+  readonly $znight: 'parameters'
+  readonly in: 'path' | 'query' | 'header' | 'cookie'
+  /** Slot name. */
+  readonly name: string
+  readonly io: 'input'
+}
+
+/** JSON Schema, or a placeholder of a Standard Schema. */
+export type SchemaTemplate = JsonSchema | SchemaPlaceholder
+
+/** An Operation Object whose schemas are {@link SchemaTemplate}s and whose parameters may be {@link ParametersPlaceholder}s. */
+export type OperationTemplate = OperationObjectOf<SchemaTemplate, ParametersPlaceholder>
+
+/** Root fields of the document known at build time. */
+export interface OpenApiDocumentTemplate {
+  readonly openapi: string
+  readonly info: InfoObject
+  readonly servers?: readonly ServerObject[]
+  readonly tags?: readonly TagObject[]
+  readonly externalDocs?: ExternalDocumentationObject
+  readonly security?: readonly SecurityRequirementObject[]
+  readonly [extension: `x-${string}`]: JsonValue | undefined
+}
+
+/** A documented operation. */
+export interface OpenApiOperationDefinition {
+  /** Controller token. */
+  readonly controller: Token
+  readonly handler: string
+  /** The compiled route method (`'ALL'` gives one definition per documented method). */
+  readonly route: string
+  readonly method: OpenApiMethod
+  /** OpenAPI path template, without the HTTP prefix (`/books/{id}`). */
+  readonly path: string
+  readonly operation: OperationTemplate
+}
+
+/** A Standard Schema converted when the document is assembled. */
+export interface OpenApiSchemaSlot {
+  /** Component name (export name of the binding: `CreateBook`). */
+  readonly name: string
+  /** The imported schema value. */
+  readonly schema: StandardSchemaV1
+  /** The JSON Schemas needed: `input` for requests, `output` for responses. */
+  readonly io: readonly ('input' | 'output')[]
+  /** Where the schema is declared (relative path), for messages. */
+  readonly source?: { readonly file: string; readonly line: number; readonly column: number }
+}
+
+/** `metadata.extensions.openapi`. */
+export interface OpenApiMetadata {
+  readonly version: 1
+  /** SHA-256 (base64url) of the section, schema values replaced by their names (stale-file detection). */
+  readonly fingerprint: string
+  readonly document: OpenApiDocumentTemplate
+  /** Sorted by path, then by method (get, put, post, delete, options, head, patch). */
+  readonly operations: readonly OpenApiOperationDefinition[]
+  /** JSON Schemas computed by the compiler from TypeScript declarations, by component name (sorted). */
+  readonly components: Readonly<Record<string, SchemaTemplate>>
+  readonly securitySchemes: Readonly<Record<string, SecuritySchemeObject>>
+  /** Standard Schemas converted at assembly, sorted by name. */
+  readonly schemas: readonly OpenApiSchemaSlot[]
+  /** Standard error components; absent with `errors: false`. */
+  readonly errors?: { readonly contentType: string; readonly schema?: string }
+  /** Descriptions of the default tags (JSDoc of the controllers), by tag name; absent when empty. */
+  readonly tagDescriptions?: Readonly<Record<string, string>>
+}
+
+declare module '@znight/core' {
+  interface ZnightExtensionsMetadata {
+    readonly openapi?: OpenApiMetadata
+  }
+}

package/src/openapi.ts

@@ -0,0 +1,55 @@
+/** The injectable `OpenApi` external and the YAML serialisation. */
+import type { OpenApiOperationView } from './build.ts'
+import type { OpenApiObject } from './types.ts'
+
+import { ErrorCode, type TypedToken, ZnightError } from '@znight/core'
+
+/**
+ * The document of the application, provided by `OpenApiPlugin` (a singleton external declared in
+ * the manifest of `@znight/openapi`).
+ *
+ * ```ts
+ * @Injectable()
+ * export class GatewayRegistration implements OnReady {
+ *   constructor(private readonly openapi: OpenApi, private readonly gateway: GatewayClient) {}
+ *   async onReady(): Promise<void> {
+ *     await this.gateway.publish(await this.openapi.json())
+ *   }
+ * }
+ * ```
+ */
+export abstract class OpenApi {
+  /** The frozen document (built on the first call in `'first-request'` mode, or when the plugin is disabled). */
+  abstract document(): Promise<OpenApiObject>
+  /** The served JSON text (2 spaces, final newline). */
+  abstract json(): Promise<string>
+  /** The YAML text (optional peer `yaml`). */
+  abstract yaml(): Promise<string>
+  /** Static view of the operations, without any schema conversion. */
+  abstract readonly operations: readonly OpenApiOperationView[]
+}
+
+/** Tokens of the externals provided by `OpenApiPlugin` (declared in the package manifest). */
+export const OpenApiTokens: {
+  /** The {@link OpenApi} singleton. */
+  readonly OpenApi: TypedToken<OpenApi>
+} = Object.freeze({ OpenApi: '@znight/openapi#OpenApi' })
+
+/** YAML text of a document (`yaml` is an optional peer, loaded lazily). */
+export async function toYaml(document: OpenApiObject): Promise<string> {
+  let module: { stringify?: (value: unknown, options?: Record<string, unknown>) => string }
+  try {
+    module = (await import('yaml')) as typeof module
+  } catch (error) {
+    throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, 'YAML output needs the optional peer dependency "yaml"', {
+      cause: error,
+      hints: ['npm install yaml'],
+    })
+  }
+  if (typeof module.stringify !== 'function') {
+    throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, 'The installed "yaml" package has no stringify()', {
+      hints: ['npm install yaml@2'],
+    })
+  }
+  return module.stringify(document, { aliasDuplicateObjects: false, lineWidth: 0 })
+}