@rhythmjs/openapi 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 rhythmjs
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @rhythmjs/openapi
+
+OpenAPI 3.1 documentation for [Rhythm](https://github.com/rhythmjs/rhythm) routers and handlers. Routes are
+documented by small single-purpose middlewares (`apiBody`, `apiResponse`, `apiTags`, …); a generator walks the
+router and produces the document; a docs middleware serves it with an interactive reference UI. Each module is
+exported by its own subpath — there is no root barrel export.
+
+Schemas are [Standard Schema v1](https://standardschema.dev): zod and valibot convert to JSON Schema out of the
+box, any other vendor via a custom converter.
+
+## Install
+
+```sh
+pnpm add @rhythmjs/openapi @rhythmjs/rhythm @rhythmjs/router
+```
+
+`@rhythmjs/router` >= 0.0.6 is required (the generator reads `router.entries`). `zod` (v4) and
+`@valibot/to-json-schema` are optional peers — install whichever your schemas need.
+
+## Quick start
+
+```ts
+import { Rhythm } from "@rhythmjs/rhythm";
+import { RhythmRouter } from "@rhythmjs/router";
+import type { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+import { apiBody, type Validated } from "@rhythmjs/openapi/body";
+import { apiParam } from "@rhythmjs/openapi/param";
+import { apiOperation } from "@rhythmjs/openapi/operation";
+import { apiResponse } from "@rhythmjs/openapi/response";
+import { apiTags } from "@rhythmjs/openapi/tags";
+import { apiBearerAuth } from "@rhythmjs/openapi/security";
+import { defineDocument } from "@rhythmjs/openapi/document";
+import { apiDocument, apiReference } from "@rhythmjs/openapi/docs";
+import { z } from "zod";
+
+const User = z.object({ id: z.string(), name: z.string() });
+const CreateUser = z.object({ name: z.string().min(1) });
+
+const users = new RhythmRouter({ prefix: "/users" })
+  .use(apiTags("users"))
+  .post<Validated<"body", typeof CreateUser>>(
+    "/",
+    apiBody(CreateUser),
+    apiOperation({ summary: "Create user", operationId: "createUser" }),
+    apiBearerAuth(),
+    apiResponse(201, { description: "Created", schema: User }),
+    (ctx) => {
+      // ctx.valid.body is fully typed as the schema output ({ name: string })
+      ctx.json({ id: "1", ...ctx.valid.body }, 201);
+    },
+  )
+  .get(
+    "/:id",
+    apiParam(z.object({ id: z.string() })),
+    apiResponse(200, { description: "The user", schema: User }),
+    (ctx) => {
+      ctx.json({ id: ctx.params.id, name: "Ada" });
+    },
+  );
+
+const config = defineDocument({
+  info: { title: "My API", version: "1.0.0" },
+  servers: [{ url: "https://api.example.com" }],
+  securitySchemes: { bearer: { type: "http", scheme: "bearer", bearerFormat: "JWT" } },
+});
+
+const app = new Rhythm<RhythmHttpContext>()
+  .use(apiDocument({ router: users, config })) // GET /openapi.json
+  .use(apiReference()) // GET /docs (Scalar; { ui: "swagger" } for Swagger UI)
+  .use(users.middleware());
+```
+
+## Request middlewares (validate + document)
+
+These take a Standard Schema, validate the request at runtime (exposing the typed output on
+`ctx.valid[target]`, same contract and 400 `ValidationFailure` shape as `@rhythmjs/middleware/validate`), and
+document the corresponding OpenAPI object. Use either these or `@rhythmjs/middleware/validate` on a route — not
+both, or the request is validated twice.
+
+- `apiBody(schema, options?)` — Request Body Object. Options: `description`, `required`, `contentType`
+  (drives extraction too: JSON, forms, or raw text), `example(s)`, `encoding`, or a full `content` map.
+- `apiQuery(schema, options?)` — query Parameter Objects, one per schema property; repeated keys become arrays.
+- `apiParam(schema, options?)` — path Parameter Objects (always `required: true`).
+- `apiHeader(schema, options?)` — header Parameter Objects (header names are lowercased).
+- `apiCookie(schema, options?)` — cookie Parameter Objects, parsed from the `cookie` header.
+
+Parameter middlewares accept per-property `overrides` for everything a schema cannot express:
+`description`, `required`, `deprecated`, `style`, `explode`, `allowReserved`, `allowEmptyValue`, `example(s)`.
+
+## Documentation-only middlewares
+
+Runtime no-ops that carry spec fragments. Apply per-route, or router-wide with `router.use(...)` — a
+router-level fragment applies to every route registered after it.
+
+- `apiOperation({ summary, description, operationId, deprecated, externalDocs, servers })`
+- `apiResponse(status, { description, schema?, contentType?, example(s)?, content?, headers?, links? })` —
+  stackable; `status` is a code, a range (`"5XX"`), or `"default"`.
+- `apiTags(...names)`
+- `apiSecurity(name, scopes?)` plus presets `apiBearerAuth()`, `apiBasicAuth()`, `apiCookieAuth()`,
+  `apiKeyAuth()`, `apiOAuth2(scopes)`, and `apiNoSecurity()` (documents `security: []`).
+- `apiExclude()` — hide a route (or a whole router via `use`).
+- `apiExtension("x-...", value)`
+- `apiCallback(name, callbackObject)`
+
+There are no model-level annotations: property documentation lives in the schema itself (zod `.describe()` /
+`.meta()`, valibot equivalents) and flows through the JSON Schema conversion.
+
+## Document config and generation
+
+Everything that is not a route concern is a plain config object (Rhythm's counterpart to NestJS's
+`DocumentBuilder`):
+
+```ts
+import { defineDocument } from "@rhythmjs/openapi/document";
+import { generate } from "@rhythmjs/openapi/generate";
+
+const config = defineDocument({
+  info: { title: "My API", version: "1.0.0" },
+  servers: [{ url: "https://api.example.com" }],
+  tags: [{ name: "users", description: "User management" }],
+  security: [{ bearer: [] }], // global security; apiNoSecurity() opts a route out
+  securitySchemes: { bearer: { type: "http", scheme: "bearer" } },
+  webhooks: { "user.created": { post: { responses: { "200": { description: "Received" } } } } },
+  components: {}, // reusable components, merged verbatim
+  extensions: { "x-audience": "public" },
+});
+
+const doc = await generate(router, config, {
+  // openapi: "3.1.1", includeUndocumented: true,
+  // converters: { arktype: (schema) => schema.toJsonSchema() },
+});
+```
+
+`generate` walks `router.entries`, merges fragments per route, converts `:id` to `{id}`, resolves schemas
+(request schemas on their input side, response schemas on their output side), and hoists `$defs` into
+`components.schemas`. Undocumented routes are included with a default `200` response
+(`includeUndocumented: false` drops them).
+
+## Serving the docs
+
+- `apiDocument({ router, config, path? })` — serves the generated JSON (default `/openapi.json`), generated
+  lazily once and cached.
+- `apiReference({ path?, specUrl?, ui?, title? })` — serves an interactive reference page (default `/docs`,
+  Scalar; `ui: "swagger"` for Swagger UI).
+
+## Not covered
+
+`OPTIONS`/`HEAD`/`TRACE` operations (the router does not route them) and Path Item-level fields (`summary`,
+per-path `servers`) — the `components.pathItems` escape hatch in the config covers the latter.

package/dist/body/body.d.ts

@@ -0,0 +1,18 @@
+import { S as ReferenceObject, a as ExampleObject, i as EncodingObject } from "../types-DeDU0OMv.js";
+import { n as MediaTypeSpec } from "../metadata-CT05Tw6j.js";
+import { a as ValidationTarget, i as ValidationIssue, n as ValidationContext, r as ValidationFailure, t as Validated } from "../runtime-CtmUGPnb.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { DeriveMiddleware } from "@rhythmjs/rhythm/types";
+//#region src/body/body.d.ts
+export interface ApiBodyOptions {
+  description?: string;
+  required?: boolean;
+  contentType?: string;
+  example?: unknown;
+  examples?: Record<string, ExampleObject | ReferenceObject>;
+  encoding?: Record<string, EncodingObject>;
+  content?: Record<string, MediaTypeSpec>;
+}
+export declare function apiBody<TSchema extends StandardSchemaV1>(schema: TSchema, options?: ApiBodyOptions): DeriveMiddleware<ValidationContext, Validated<"body", TSchema>>;
+//#endregion
+export type { Validated, ValidationContext, ValidationFailure, ValidationIssue, ValidationTarget };

package/dist/body/body.js

@@ -0,0 +1,18 @@
+import { a as schemaMiddleware, t as bodyExtractor } from "../runtime-CCU9lE2d.js";
+//#region src/body/body.ts
+function apiBody(schema, options = {}) {
+	const contentType = options.contentType ?? "application/json";
+	const content = options.content ?? { [contentType]: {
+		schema,
+		...options.example !== void 0 ? { example: options.example } : {},
+		...options.examples ? { examples: options.examples } : {},
+		...options.encoding ? { encoding: options.encoding } : {}
+	} };
+	return schemaMiddleware("body", schema, { requestBody: {
+		...options.description ? { description: options.description } : {},
+		required: options.required ?? true,
+		content
+	} }, bodyExtractor(contentType));
+}
+//#endregion
+export { apiBody };

package/dist/callback/callback.d.ts

@@ -0,0 +1,6 @@
+import { S as ReferenceObject, t as CallbackObject } from "../types-DeDU0OMv.js";
+import { Middleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/callback/callback.d.ts
+export declare function apiCallback(name: string, callback: CallbackObject | ReferenceObject): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/callback/callback.js

@@ -0,0 +1,7 @@
+import { docOnly } from "../metadata/metadata.js";
+//#region src/callback/callback.ts
+function apiCallback(name, callback) {
+	return docOnly({ callbacks: { [name]: callback } });
+}
+//#endregion
+export { apiCallback };

package/dist/cookie/cookie.d.ts

@@ -0,0 +1,10 @@
+import { s as ParameterOverride } from "../metadata-CT05Tw6j.js";
+import { n as ValidationContext, t as Validated } from "../runtime-CtmUGPnb.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { DeriveMiddleware } from "@rhythmjs/rhythm/types";
+//#region src/cookie/cookie.d.ts
+export interface ApiCookieOptions {
+  overrides?: Record<string, ParameterOverride>;
+}
+export declare function apiCookie<TSchema extends StandardSchemaV1>(schema: TSchema, options?: ApiCookieOptions): DeriveMiddleware<ValidationContext, Validated<"cookie", TSchema>>;
+//#endregion

package/dist/cookie/cookie.js

@@ -0,0 +1,14 @@
+import { a as schemaMiddleware, n as collectCookies } from "../runtime-CCU9lE2d.js";
+//#region src/cookie/cookie.ts
+function apiCookie(schema, options = {}) {
+	return schemaMiddleware("cookie", schema, { parameters: [{
+		in: "cookie",
+		schema,
+		...options.overrides ? { overrides: options.overrides } : {}
+	}] }, (ctx) => ({
+		ok: true,
+		value: collectCookies(ctx.request)
+	}));
+}
+//#endregion
+export { apiCookie };

package/dist/docs/docs.d.ts

@@ -0,0 +1,19 @@
+import { OpenAPIConfig } from "../document/document.js";
+import { GenerateOptions, RouterSource } from "../generate/generate.js";
+import { Middleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/docs/docs.d.ts
+export interface ApiDocumentOptions extends GenerateOptions {
+  path?: string;
+  router: RouterSource;
+  config: OpenAPIConfig;
+}
+export declare function apiDocument(options: ApiDocumentOptions): Middleware<RhythmHttpContext>;
+export interface ApiReferenceOptions {
+  path?: string;
+  specUrl?: string;
+  ui?: "scalar" | "swagger";
+  title?: string;
+}
+export declare function apiReference(options?: ApiReferenceOptions): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/docs/docs.js

@@ -0,0 +1,66 @@
+import { generate } from "../generate/generate.js";
+//#region src/docs/docs.ts
+function apiDocument(options) {
+	const path = options.path ?? "/openapi.json";
+	let cached;
+	return async (ctx, next) => {
+		if (ctx.request.method !== "GET" || new URL(ctx.request.url).pathname !== path) {
+			await next();
+			return;
+		}
+		cached ??= generate(options.router, options.config, options);
+		ctx.json(await cached);
+	};
+}
+function escapeHtml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+function scalarPage(specUrl, title) {
+	return `<!doctype html>
+<html>
+  <head>
+    <title>${title}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script id="api-reference" data-url="${specUrl}"><\/script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"><\/script>
+  </body>
+</html>`;
+}
+function swaggerPage(specUrl, title) {
+	return `<!doctype html>
+<html>
+  <head>
+    <title>${title}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"><\/script>
+    <script>
+      window.onload = () => {
+        window.ui = SwaggerUIBundle({ url: "${specUrl}", dom_id: "#swagger-ui" });
+      };
+    <\/script>
+  </body>
+</html>`;
+}
+function apiReference(options = {}) {
+	const path = options.path ?? "/docs";
+	const specUrl = escapeHtml(options.specUrl ?? "/openapi.json");
+	const title = escapeHtml(options.title ?? "API Reference");
+	const page = options.ui === "swagger" ? swaggerPage(specUrl, title) : scalarPage(specUrl, title);
+	return async (ctx, next) => {
+		if (ctx.request.method !== "GET" || new URL(ctx.request.url).pathname !== path) {
+			await next();
+			return;
+		}
+		ctx.html(page);
+	};
+}
+//#endregion
+export { apiDocument, apiReference };

package/dist/document/document.d.ts

@@ -0,0 +1,16 @@
+import { D as SecurityRequirementObject, O as SecuritySchemeObject, S as ReferenceObject, b as PathItemObject, j as TagObject, k as ServerObject, l as InfoObject, n as ComponentsObject, s as ExternalDocsObject } from "../types-DeDU0OMv.js";
+//#region src/document/document.d.ts
+export interface OpenAPIConfig {
+  info: InfoObject;
+  jsonSchemaDialect?: string;
+  servers?: ServerObject[];
+  tags?: TagObject[];
+  externalDocs?: ExternalDocsObject;
+  security?: SecurityRequirementObject[];
+  securitySchemes?: Record<string, SecuritySchemeObject | ReferenceObject>;
+  components?: ComponentsObject;
+  webhooks?: Record<string, PathItemObject>;
+  extensions?: Record<`x-${string}`, unknown>;
+}
+export declare function defineDocument(config: OpenAPIConfig): OpenAPIConfig;
+//#endregion

package/dist/document/document.js

@@ -0,0 +1,6 @@
+//#region src/document/document.ts
+function defineDocument(config) {
+	return config;
+}
+//#endregion
+export { defineDocument };

package/dist/exclude/exclude.d.ts

@@ -0,0 +1,5 @@
+import { Middleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/exclude/exclude.d.ts
+export declare function apiExclude(): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/exclude/exclude.js

@@ -0,0 +1,7 @@
+import { docOnly } from "../metadata/metadata.js";
+//#region src/exclude/exclude.ts
+function apiExclude() {
+	return docOnly({ exclude: true });
+}
+//#endregion
+export { apiExclude };

package/dist/extension/extension.d.ts

@@ -0,0 +1,5 @@
+import { Middleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/extension/extension.d.ts
+export declare function apiExtension(name: `x-${string}`, value: unknown): Middleware<RhythmHttpContext>;
+//#endregion

package/dist/extension/extension.js

@@ -0,0 +1,8 @@
+import { docOnly } from "../metadata/metadata.js";
+//#region src/extension/extension.ts
+function apiExtension(name, value) {
+	if (!name.startsWith("x-")) throw new TypeError(`OpenAPI extension names must start with "x-", got "${String(name)}"`);
+	return docOnly({ extensions: { [name]: value } });
+}
+//#endregion
+export { apiExtension };

package/dist/generate/generate.d.ts

@@ -0,0 +1,21 @@
+import { h as OpenAPIObject } from "../types-DeDU0OMv.js";
+import { OpenAPIConfig } from "../document/document.js";
+import { t as ResolverOptions } from "../resolver-sb66uMQ-.js";
+//#region src/generate/generate.d.ts
+export interface RouterSource {
+  readonly entries: ReadonlyArray<{
+    readonly kind: "middleware";
+    readonly fn: unknown;
+  } | {
+    readonly kind: "route";
+    readonly method: string;
+    readonly path: string;
+    readonly handlers: readonly unknown[];
+  }>;
+}
+export interface GenerateOptions extends ResolverOptions {
+  openapi?: string;
+  includeUndocumented?: boolean;
+}
+export declare function generate(router: RouterSource, config: OpenAPIConfig, options?: GenerateOptions): Promise<OpenAPIObject>;
+//#endregion

package/dist/generate/generate.js

@@ -0,0 +1,169 @@
+import { fragmentOf } from "../metadata/metadata.js";
+import { resolveSchema } from "../resolver/resolver.js";
+//#region src/generate/generate.ts
+const DEFS_PREFIX = "#/$defs/";
+function rewriteRefs(node, rename) {
+	if (Array.isArray(node)) return node.map((item) => rewriteRefs(item, rename));
+	if (typeof node !== "object" || node === null) return node;
+	const out = {};
+	for (const [key, value] of Object.entries(node)) if (key === "$ref" && typeof value === "string" && value.startsWith(DEFS_PREFIX)) {
+		const name = value.slice(8);
+		out[key] = `#/components/schemas/${rename.get(name) ?? name}`;
+	} else out[key] = rewriteRefs(value, rename);
+	return out;
+}
+function hoistDefs(schema, sink) {
+	if (typeof schema !== "object" || schema === null || !("$defs" in schema)) return schema;
+	const { $defs, ...rest } = schema;
+	const defs = $defs;
+	const rename = /* @__PURE__ */ new Map();
+	for (const [name, def] of Object.entries(defs)) {
+		let final = name;
+		let suffix = 2;
+		while (final in sink && JSON.stringify(sink[final]) !== JSON.stringify(def)) final = `${name}_${suffix++}`;
+		rename.set(name, final);
+	}
+	for (const [name, def] of Object.entries(defs)) sink[rename.get(name)] = rewriteRefs(def, rename);
+	return rewriteRefs(rest, rename);
+}
+function isReference(value) {
+	return "$ref" in value;
+}
+function toOpenAPIPath(path) {
+	return path.split("/").map((segment) => {
+		if (segment.startsWith(":")) return `{${segment.slice(1)}}`;
+		if (segment === "*") return "{wildcard}";
+		return segment;
+	}).join("/");
+}
+async function toMediaType(spec, io, resolve) {
+	const { schema, ...rest } = spec;
+	return {
+		...rest,
+		...schema !== void 0 ? { schema: await resolve(schema, io) } : {}
+	};
+}
+async function toContent(content, io, resolve) {
+	const out = {};
+	for (const [mediaType, spec] of Object.entries(content)) out[mediaType] = await toMediaType(spec, io, resolve);
+	return out;
+}
+async function toRequestBody(spec, resolve) {
+	const { content, ...rest } = spec;
+	return {
+		...rest,
+		content: await toContent(content, "input", resolve)
+	};
+}
+async function toResponse(spec, resolve) {
+	const { content, headers, ...rest } = spec;
+	const out = { ...rest };
+	if (content) out.content = await toContent(content, "output", resolve);
+	if (headers) {
+		const converted = {};
+		for (const [name, header] of Object.entries(headers)) if (isReference(header)) converted[name] = header;
+		else {
+			const { schema, ...headerRest } = header;
+			converted[name] = {
+				...headerRest,
+				...schema !== void 0 ? { schema: await resolve(schema, "output") } : {}
+			};
+		}
+		out.headers = converted;
+	}
+	return out;
+}
+async function expandParameters(group, sink, resolve) {
+	const resolved = await resolve(group.schema, "input");
+	if (typeof resolved !== "object" || resolved === null) return;
+	const properties = resolved.properties ?? {};
+	const required = Array.isArray(resolved.required) ? resolved.required : [];
+	for (const [name, propertySchema] of Object.entries(properties)) {
+		const { required: overrideRequired, ...overrideRest } = group.overrides?.[name] ?? {};
+		const parameter = {
+			name,
+			in: group.in,
+			required: group.in === "path" ? true : overrideRequired ?? required.includes(name),
+			schema: propertySchema,
+			...overrideRest
+		};
+		sink.set(`${group.in}:${name}`, parameter);
+	}
+}
+async function buildOperation(fragments, resolve) {
+	const tags = [];
+	const security = [];
+	let noSecurity = false;
+	const parameters = /* @__PURE__ */ new Map();
+	let requestBody;
+	const responses = {};
+	const callbacks = {};
+	const fields = {};
+	const extensions = {};
+	for (const fragment of fragments) {
+		if (fragment.exclude) return void 0;
+		if (fragment.operation) Object.assign(fields, fragment.operation);
+		for (const tag of fragment.tags ?? []) if (!tags.includes(tag)) tags.push(tag);
+		if (fragment.security === "none") noSecurity = true;
+		else for (const requirement of fragment.security ?? []) if (!security.some((existing) => JSON.stringify(existing) === JSON.stringify(requirement))) security.push(requirement);
+		for (const group of fragment.parameters ?? []) await expandParameters(group, parameters, resolve);
+		if (fragment.requestBody) requestBody = await toRequestBody(fragment.requestBody, resolve);
+		for (const [status, spec] of Object.entries(fragment.responses ?? {})) responses[status] = isReference(spec) ? spec : await toResponse(spec, resolve);
+		Object.assign(callbacks, fragment.callbacks);
+		Object.assign(extensions, fragment.extensions);
+	}
+	return {
+		...tags.length ? { tags } : {},
+		...fields,
+		...parameters.size ? { parameters: [...parameters.values()] } : {},
+		...requestBody ? { requestBody } : {},
+		responses: Object.keys(responses).length ? responses : { "200": { description: "Successful response" } },
+		...Object.keys(callbacks).length ? { callbacks } : {},
+		...noSecurity ? { security: [] } : security.length ? { security } : {},
+		...extensions
+	};
+}
+async function generate(router, config, options = {}) {
+	const schemas = {};
+	const resolve = async (schema, io) => hoistDefs(await resolveSchema(schema, io, options), schemas);
+	const paths = {};
+	const inherited = [];
+	for (const entry of router.entries) {
+		if (entry.kind === "middleware") {
+			const fragment = fragmentOf(entry.fn);
+			if (fragment) inherited.push(fragment);
+			continue;
+		}
+		const own = entry.handlers.map(fragmentOf).filter((fragment) => !!fragment);
+		if (!own.length && !(options.includeUndocumented ?? true)) continue;
+		const operation = await buildOperation([...inherited, ...own], resolve);
+		if (!operation) continue;
+		const path = toOpenAPIPath(entry.path);
+		const method = entry.method.toLowerCase();
+		(paths[path] ??= {})[method] = operation;
+	}
+	const components = { ...config.components };
+	if (config.securitySchemes) components.securitySchemes = {
+		...components.securitySchemes,
+		...config.securitySchemes
+	};
+	if (Object.keys(schemas).length) components.schemas = {
+		...components.schemas,
+		...schemas
+	};
+	return {
+		openapi: options.openapi ?? "3.1.1",
+		info: config.info,
+		...config.jsonSchemaDialect ? { jsonSchemaDialect: config.jsonSchemaDialect } : {},
+		...config.servers ? { servers: config.servers } : {},
+		paths,
+		...config.webhooks ? { webhooks: config.webhooks } : {},
+		...Object.keys(components).length ? { components } : {},
+		...config.security ? { security: config.security } : {},
+		...config.tags ? { tags: config.tags } : {},
+		...config.externalDocs ? { externalDocs: config.externalDocs } : {},
+		...config.extensions
+	};
+}
+//#endregion
+export { generate };

package/dist/header/header.d.ts

@@ -0,0 +1,10 @@
+import { s as ParameterOverride } from "../metadata-CT05Tw6j.js";
+import { n as ValidationContext, t as Validated } from "../runtime-CtmUGPnb.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { DeriveMiddleware } from "@rhythmjs/rhythm/types";
+//#region src/header/header.d.ts
+export interface ApiHeaderOptions {
+  overrides?: Record<string, ParameterOverride>;
+}
+export declare function apiHeader<TSchema extends StandardSchemaV1>(schema: TSchema, options?: ApiHeaderOptions): DeriveMiddleware<ValidationContext, Validated<"header", TSchema>>;
+//#endregion

package/dist/header/header.js

@@ -0,0 +1,14 @@
+import { a as schemaMiddleware, r as collectHeaders } from "../runtime-CCU9lE2d.js";
+//#region src/header/header.ts
+function apiHeader(schema, options = {}) {
+	return schemaMiddleware("header", schema, { parameters: [{
+		in: "header",
+		schema,
+		...options.overrides ? { overrides: options.overrides } : {}
+	}] }, (ctx) => ({
+		ok: true,
+		value: collectHeaders(ctx.request)
+	}));
+}
+//#endregion
+export { apiHeader };

package/dist/metadata/metadata.d.ts

@@ -0,0 +1,2 @@
+import { a as OperationFragment, c as RequestBodySpec, d as docOnly, f as fragmentOf, i as OperationFields, l as ResponseSpec, n as MediaTypeSpec, o as ParameterGroupSpec, p as withFragment, r as OPENAPI_METADATA, s as ParameterOverride, t as HeaderSpec, u as SchemaLike } from "../metadata-CT05Tw6j.js";
+export { HeaderSpec, MediaTypeSpec, OPENAPI_METADATA, OperationFields, OperationFragment, ParameterGroupSpec, ParameterOverride, RequestBodySpec, ResponseSpec, SchemaLike, docOnly, fragmentOf, withFragment };

package/dist/metadata/metadata.js

@@ -0,0 +1,17 @@
+//#region src/metadata/metadata.ts
+const OPENAPI_METADATA = Symbol.for("rhythmjs.openapi");
+function withFragment(fn, fragment) {
+	Object.defineProperty(fn, OPENAPI_METADATA, { value: fragment });
+	return fn;
+}
+function fragmentOf(fn) {
+	if (typeof fn !== "function") return void 0;
+	return fn[OPENAPI_METADATA];
+}
+function docOnly(fragment) {
+	return withFragment(async (_ctx, next) => {
+		await next();
+	}, fragment);
+}
+//#endregion
+export { OPENAPI_METADATA, docOnly, fragmentOf, withFragment };