@kizunajs/openapi 2.0.0-beta.0

package/LICENSE.MD

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Sondre Ørland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @kizunajs/openapi
+
+`@kizunajs/openapi` generates an OpenAPI 3.1.0 document from your routes, and serves it with a reference UI on any adapter.
+
+## Installation
+
+```sh
+pnpm add @kizunajs/openapi
+```
+
+## Usage
+
+Name the plugin under `plugins` in your config, and `api.mount` serves the document and its reference UI:
+
+```ts
+// kizuna.config.ts
+import { defineConfig } from 'kizunajs';
+import { expressAdapter } from '@kizunajs/express';
+import { openApiPlugin } from '@kizunajs/openapi';
+import { routes } from './src/routes';
+
+export default defineConfig({
+    adapter: expressAdapter(),
+    routes,
+    plugins: [
+        openApiPlugin({
+            info: {
+                title: 'My API',
+                version: '1.0.0',
+            },
+            docsPath: '/docs',
+        }),
+    ],
+});
+```
+
+## Documentation
+
+[OpenAPI generation](https://kizunajs.com/docs/openapi)

package/dist/index.cjs

@@ -0,0 +1,649 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+let kizunajs_plugin = require("kizunajs/plugin");
+let kizunajs_adapter = require("kizunajs/adapter");
+let yaml = require("yaml");
+let kizunajs_generator = require("kizunajs/generator");
+let kizunajs = require("kizunajs");
+//#region src/generator.ts
+const streamJsonSchema = (response, toJsonSchema) => {
+	const mode = (0, kizunajs_generator.streamMode)(response);
+	if (mode === "text") return { type: "string" };
+	if (mode === "binary") return {
+		type: "string",
+		format: "binary"
+	};
+	const eventFields = {
+		id: { type: "string" },
+		retry: { type: "integer" }
+	};
+	const message = (data, event) => ({
+		type: "object",
+		required: event === void 0 ? ["data"] : ["event", "data"],
+		properties: {
+			...event === void 0 ? {} : { event: { const: event } },
+			data,
+			...eventFields
+		}
+	});
+	if ((0, kizunajs_generator.isNamedStream)(response.stream)) return { oneOf: Object.entries(response.stream).map(([event, schema]) => message(toJsonSchema(schema, "output"), event)) };
+	return message(toJsonSchema(response.stream, "output"));
+};
+const convertPath = (path) => {
+	const { segments } = (0, kizunajs_generator.parsePath)(path);
+	return segments.map((segment) => segment.kind === "literal" ? segment.value : `{${segment.value}}`).join("");
+};
+const COMPONENT_REF_BASE = "#/components/schemas/";
+const ZOD_DEF_REF_BASE = "#/$defs/";
+const omit = (input, keys) => {
+	const result = {};
+	for (const [key, value] of Object.entries(input)) if (!keys.includes(key)) result[key] = value;
+	return result;
+};
+const rewriteRefs = (value) => {
+	if (Array.isArray(value)) return value.map(rewriteRefs);
+	if (value && typeof value === "object") {
+		const result = {};
+		for (const [key, child] of Object.entries(value)) if (key === "$ref" && typeof child === "string" && child.startsWith(ZOD_DEF_REF_BASE)) result[key] = COMPONENT_REF_BASE + child.slice(8);
+		else result[key] = rewriteRefs(child);
+		return result;
+	}
+	return value;
+};
+const applyFileBinary = (zodSchema, jsonSchema) => {
+	if (!jsonSchema || typeof jsonSchema !== "object") return;
+	const shape = (0, kizunajs_generator.readObjectShape)(zodSchema);
+	if (!shape) return;
+	const properties = jsonSchema.properties;
+	if (!properties) return;
+	for (const [key, child] of Object.entries(shape)) if ((0, kizunajs_generator.isFileSchema)(child)) properties[key] = {
+		type: "string",
+		format: "binary"
+	};
+	else applyFileBinary(child, properties[key]);
+};
+const buildDiscriminatorBlock = (propertyName, options) => {
+	const mapping = {};
+	let mappingComplete = true;
+	for (const variant of options) {
+		const variantId = (0, kizunajs_generator.readMetaId)(variant);
+		const literal = (0, kizunajs_generator.readDiscriminatorLiteral)(variant, propertyName);
+		if (variantId === void 0 || literal === void 0) {
+			mappingComplete = false;
+			break;
+		}
+		mapping[String(literal)] = COMPONENT_REF_BASE + variantId;
+	}
+	return mappingComplete && Object.keys(mapping).length > 0 ? {
+		propertyName,
+		mapping
+	} : { propertyName };
+};
+/**
+* kizuna's metadata widens JSON Schema: `deprecated` may carry a message and
+* `example` holds one value or several. Emit `deprecated: true` and an
+* `examples` array; the message stays in outputs with a place for it, like
+* Swift's `@available`.
+*/
+const normalizeMeta = ({ jsonSchema }) => {
+	if (typeof jsonSchema.deprecated === "string") jsonSchema.deprecated = true;
+	if ("example" in jsonSchema) {
+		const given = Array.isArray(jsonSchema.example) ? jsonSchema.example : [jsonSchema.example];
+		const declared = Array.isArray(jsonSchema.examples) ? jsonSchema.examples : [];
+		jsonSchema.examples = [...given, ...declared];
+		delete jsonSchema.example;
+	}
+};
+const toJsonSchema = (schema, io = "output") => {
+	const id = (0, kizunajs_generator.readMetaId)(schema);
+	if (id) return { $ref: COMPONENT_REF_BASE + id };
+	const discriminated = (0, kizunajs_generator.readDiscriminatedUnion)(schema);
+	if (discriminated) return {
+		...rewriteRefs(omit(zod.z.toJSONSchema(schema, {
+			unrepresentable: "any",
+			io,
+			override: normalizeMeta
+		}), ["$defs", "$schema"])),
+		discriminator: buildDiscriminatorBlock(discriminated.discriminator, discriminated.options)
+	};
+	const result = rewriteRefs(omit(zod.z.toJSONSchema(schema, {
+		unrepresentable: "any",
+		io,
+		override: normalizeMeta
+	}), ["$defs", "$schema"]));
+	applyFileBinary(schema, result);
+	return result;
+};
+const buildComponentSchemas = () => {
+	const discriminators = /* @__PURE__ */ new Map();
+	const modelRegistry = zod.z.registry();
+	for (const [id, schema] of (0, kizunajs_generator.globalRegistrySchemas)().entries()) {
+		modelRegistry.add(schema, (0, kizunajs_generator.readMeta)(schema));
+		const def = (0, kizunajs_generator.readDiscriminatedUnion)(schema);
+		if (def) discriminators.set(id, buildDiscriminatorBlock(def.discriminator, def.options));
+	}
+	const schemas = zod.z.toJSONSchema(modelRegistry, {
+		uri: (id) => COMPONENT_REF_BASE + id,
+		unrepresentable: "any",
+		io: "output",
+		override: normalizeMeta
+	}).schemas;
+	const cleaned = {};
+	for (const [id, schema] of Object.entries(schemas)) {
+		const base = rewriteRefs(omit(schema, [
+			"$schema",
+			"$defs",
+			"$id"
+		]));
+		const discriminator = discriminators.get(id);
+		cleaned[id] = discriminator ? {
+			...base,
+			discriminator
+		} : base;
+	}
+	return Object.keys(cleaned).length > 0 ? cleaned : void 0;
+};
+const deriveHeadOperation = (getOperation) => {
+	const operation = structuredClone(getOperation);
+	delete operation.operationId;
+	for (const response of Object.values(operation.responses)) delete response.content;
+	return operation;
+};
+const openApiGenerator = (0, kizunajs_generator.createGenerator)((options, api) => {
+	const paths = {};
+	return {
+		processRoute({ routeKey, route, routeTags, deprecated }) {
+			const openApiPath = convertPath(route.path);
+			const method = route.method.toLowerCase();
+			let operation = {
+				summary: route.summary,
+				description: route.description,
+				responses: {}
+			};
+			if (options.setOperationId) operation.operationId = options.setOperationId === "concatenated-path" ? routeKey : routeKey.slice(routeKey.lastIndexOf(".") + 1);
+			if (deprecated) operation.deprecated = true;
+			const resolveTagTitle = (key) => options.tagLookup?.get(key)?.title ?? key;
+			const mergedTags = [...new Set([...routeTags, ...route.tags ?? []].map(resolveTagTitle))];
+			if (mergedTags.length > 0) operation.tags = mergedTags;
+			if (route.security && route.security.length > 0) {
+				const emittedSecurity = toOpenApiSecurity(route.security, api);
+				if (emittedSecurity.length > 0) operation.security = emittedSecurity;
+				const customGuards = customGuardsFor(route.security, api);
+				if (customGuards.length > 0) operation["x-kizuna-guarded"] = customGuards;
+				if (route.roles !== void 0) operation["x-kizuna-roles"] = [...route.roles];
+				if (route.requires !== void 0) operation["x-kizuna-requires"] = requiresExtension(route.requires);
+			}
+			if (route.externalDocs) operation.externalDocs = route.externalDocs;
+			const parameters = [];
+			const pathParamNames = (0, kizunajs_generator.parsePath)(route.path).paramNames;
+			if (pathParamNames.length > 0) {
+				const pathProperties = (route.pathParams ? toJsonSchema(route.pathParams, "input") : void 0)?.properties ?? {};
+				for (const name of pathParamNames) parameters.push({
+					name,
+					in: "path",
+					required: true,
+					schema: pathProperties[name] ?? { type: "string" }
+				});
+			}
+			if (route.query) {
+				const querySchema = toJsonSchema(route.query, "input");
+				const queryProperties = querySchema.properties ?? {};
+				const queryRequired = querySchema.required ?? [];
+				for (const [name, valueSchema] of Object.entries(queryProperties)) parameters.push({
+					name,
+					in: "query",
+					required: queryRequired.includes(name),
+					schema: valueSchema
+				});
+			}
+			if (route.headers) {
+				const headersSchema = toJsonSchema(route.headers, "input");
+				const headerProperties = headersSchema.properties ?? {};
+				const headerRequired = headersSchema.required ?? [];
+				for (const [name, valueSchema] of Object.entries(headerProperties)) parameters.push({
+					name,
+					in: "header",
+					required: headerRequired.includes(name),
+					schema: valueSchema
+				});
+			}
+			if (parameters.length > 0) operation.parameters = parameters;
+			if (route.body && !(0, kizunajs_generator.isVoidSchema)(route.body)) {
+				const contentType = route.contentType ?? "application/json";
+				operation.requestBody = {
+					required: true,
+					content: { [contentType]: { schema: toJsonSchema(route.body, "input") } }
+				};
+			}
+			for (const [statusKey, responseValue] of Object.entries(route.responses)) {
+				const headersSchema = (0, kizunajs_generator.resolveResponseHeaders)(responseValue);
+				const description = (0, kizunajs.getStatusText)(Number(statusKey));
+				const headersObject = headersSchema ? Object.fromEntries(Object.entries(toJsonSchema(headersSchema, "output").properties ?? {}).map(([name, schema]) => [name, {
+					schema,
+					required: false
+				}])) : void 0;
+				if ((0, kizunajs_generator.isStreamResponse)(responseValue)) {
+					operation.responses[statusKey] = {
+						description,
+						...headersObject ? { headers: headersObject } : {},
+						content: { [(0, kizunajs_generator.streamContentType)(responseValue)]: { schema: streamJsonSchema(responseValue, toJsonSchema) } }
+					};
+					continue;
+				}
+				const bodySchema = (0, kizunajs_generator.resolveResponseBody)(responseValue);
+				const mediaType = (0, kizunajs_generator.resolveResponseContentType)(responseValue) ?? (Number(statusKey) >= 400 ? "application/problem+json" : "application/json");
+				operation.responses[statusKey] = {
+					description,
+					...headersObject ? { headers: headersObject } : {},
+					...!(0, kizunajs_generator.isVoidSchema)(bodySchema) && route.method !== "HEAD" ? { content: { [mediaType]: { schema: (0, kizunajs_generator.isBinarySchema)(bodySchema) ? {
+						type: "string",
+						format: "binary"
+					} : toJsonSchema(bodySchema, "output") } } } : {}
+				};
+			}
+			if (route.body || route.query) {
+				const validationSchema = {
+					type: "object",
+					required: [
+						"type",
+						"title",
+						"status",
+						"detail",
+						"errors"
+					],
+					properties: {
+						type: { type: "string" },
+						title: { type: "string" },
+						status: { type: "integer" },
+						detail: { type: "string" },
+						errors: {
+							type: "array",
+							items: {
+								type: "object",
+								required: [
+									"code",
+									"path",
+									"message"
+								],
+								properties: {
+									code: { type: "string" },
+									path: {
+										type: "array",
+										items: { type: "string" }
+									},
+									message: { type: "string" }
+								}
+							}
+						}
+					}
+				};
+				const existing = operation.responses["400"];
+				if (existing) {
+					const existingSchema = existing.content?.["application/problem+json"]?.schema;
+					operation.responses["400"] = {
+						description: (0, kizunajs.getStatusText)(400),
+						content: { "application/problem+json": { schema: { oneOf: [existingSchema, validationSchema].filter(Boolean) } } }
+					};
+				} else operation.responses["400"] = {
+					description: (0, kizunajs.getStatusText)(400),
+					content: { "application/problem+json": { schema: validationSchema } }
+				};
+			}
+			const announced = (0, kizunajs_generator.deprecationHeaders)(route);
+			if (Object.keys(announced).length > 0) {
+				const documented = {};
+				if (announced["deprecation"]) documented["Deprecation"] = {
+					description: "The date the route became deprecated, per RFC 9745.",
+					schema: { type: "string" }
+				};
+				if (announced["sunset"]) documented["Sunset"] = {
+					description: "When the route will be removed, per RFC 8594.",
+					schema: { type: "string" }
+				};
+				if (announced["link"]) documented["Link"] = {
+					description: "Links to documentation about the deprecation and the retirement policy.",
+					schema: { type: "string" }
+				};
+				for (const response of Object.values(operation.responses)) response.headers = {
+					...documented,
+					...response.headers
+				};
+			}
+			for (const [statusKey, response] of Object.entries(operation.responses)) {
+				const declared = route.responses[Number(statusKey)];
+				const policy = (0, kizunajs_generator.cacheHeaders)((0, kizunajs_generator.resolveResponseCache)(declared));
+				const documented = {};
+				if (policy["cache-control"]) documented["Cache-Control"] = {
+					description: "How this response may be cached, per RFC 9111.",
+					schema: {
+						type: "string",
+						example: policy["cache-control"]
+					}
+				};
+				if (policy["vary"]) documented["Vary"] = {
+					description: "The request headers that change this response, which a cache keys on.",
+					schema: {
+						type: "string",
+						example: policy["vary"]
+					}
+				};
+				if ((0, kizunajs_generator.resolveResponseEtag)(declared)) documented["ETag"] = {
+					description: "The entity tag of this response, per RFC 9110. Send it back as `If-None-Match` to be answered `304 Not Modified` when it still holds.",
+					schema: { type: "string" }
+				};
+				if (Object.keys(documented).length === 0) continue;
+				response.headers = {
+					...documented,
+					...response.headers
+				};
+			}
+			if (options.operationMapper) operation = options.operationMapper(operation, route, routeKey);
+			if (!paths[openApiPath]) paths[openApiPath] = {};
+			paths[openApiPath][method] = operation;
+		},
+		finalize() {
+			if (options.derivedHead) for (const operations of Object.values(paths)) {
+				if (!operations["get"] || operations["head"]) continue;
+				operations["head"] = deriveHeadOperation(operations["get"]);
+			}
+			const document = {
+				openapi: options.openApiVersion ?? "3.1.0",
+				info: options.info,
+				paths
+			};
+			if (options.servers) document.servers = options.servers;
+			if (options.externalDocs) document.externalDocs = options.externalDocs;
+			const componentSchemas = buildComponentSchemas();
+			const securitySchemes = buildSecuritySchemes(api);
+			if (componentSchemas || securitySchemes) document.components = {
+				...securitySchemes ? { securitySchemes } : {},
+				...componentSchemas ? { schemas: componentSchemas } : {}
+			};
+			const renderer = (format) => {
+				if (format === "yaml") return (0, yaml.stringify)(document);
+				return document;
+			};
+			return renderer;
+		}
+	};
+});
+/**
+* The permissions a route requires, as `x-kizuna-requires`: what is acted on,
+* mapped to the verbs the caller has to hold.
+*/
+const requiresExtension = (requires) => Object.fromEntries(Object.entries(requires).map(([resource, verbs]) => [resource, [...verbs]]));
+/**
+* Whether a scheme is a `custom` identity: registered, but with no OpenAPI scheme
+* to emit. Dropped from `security`, surfaced under `x-kizuna-guarded`.
+*/
+const isCustomScheme = (name, api) => {
+	const scheme = api.securitySchemes?.[name];
+	return scheme !== void 0 && scheme.openapi === void 0;
+};
+/**
+* Map a route's resolved `security` (scheme names / `{ scheme: scopes }` maps)
+* to the OpenAPI `operation.security` shape. Any `custom` scheme is dropped (see
+* {@link isCustomScheme}); a requirement object left empty is omitted.
+*/
+const toOpenApiSecurity = (security, api) => {
+	const emittedName = (name) => api.securitySchemes?.[name]?.scheme ?? name;
+	const result = [];
+	for (const entry of security) {
+		if (typeof entry === "string") {
+			if (!isCustomScheme(entry, api)) result.push({ [emittedName(entry)]: [] });
+			continue;
+		}
+		const describable = Object.entries(entry).filter(([scheme]) => !isCustomScheme(scheme, api));
+		if (describable.length > 0) result.push(Object.fromEntries(describable.map(([scheme, scopes]) => [emittedName(scheme), [...scopes ?? []]])));
+	}
+	return result;
+};
+/**
+* The `custom` schemes guarding a route, in their registered names, for the
+* `x-kizuna-guarded` extension.
+*/
+const customGuardsFor = (security, api) => {
+	const emittedName = (name) => api.securitySchemes?.[name]?.scheme ?? name;
+	const names = [];
+	for (const entry of security) {
+		const schemeNames = typeof entry === "string" ? [entry] : Object.keys(entry);
+		for (const name of schemeNames) if (isCustomScheme(name, api) && !names.includes(emittedName(name))) names.push(emittedName(name));
+	}
+	return names;
+};
+/**
+* Build the `components.securitySchemes` object from the identities registered
+* on the api. Each contributes its OpenAPI definition under its name.
+*/
+const buildSecuritySchemes = (api) => {
+	const schemes = api.securitySchemes;
+	if (!schemes || Object.keys(schemes).length === 0) return void 0;
+	const result = {};
+	for (const [name, scheme] of Object.entries(schemes)) {
+		if (!scheme.openapi) continue;
+		result[scheme.scheme ?? name] = scheme.openapi;
+	}
+	return Object.keys(result).length > 0 ? result : void 0;
+};
+const buildTagLookup = (api) => new Map(Object.entries(api.tags?.tags ?? {}));
+/**
+* Document-level tag definitions from the api's declared tag set, one
+* entry per declared tag, in declaration order, named by its `title`.
+*/
+const tagsFromApi = (api) => {
+	const declared = api.tags?.tags;
+	if (!declared) return [];
+	const tags = [];
+	for (const options of Object.values(declared)) {
+		const entry = { name: options.title };
+		if (options.description) entry.description = options.description;
+		if (options.externalDocs) entry.externalDocs = options.externalDocs;
+		tags.push(entry);
+	}
+	return tags;
+};
+/**
+* So a build step does not restate the options and drift from what is served.
+*/
+const optionsFromInstalledPlugin = (api) => {
+	for (const declaration of Object.values(api.plugins ?? {})) if (declaration.slug === "openApi") return declaration.props;
+	throw new Error("generateOpenApi reads its options from the config. Name `openApiPlugin` under `plugins` with the API's `info`.");
+};
+/**
+* Render from options held directly, for the plugin's own routes.
+*/
+function renderOpenApi(api, options) {
+	const renderer = openApiGenerator(api, {
+		...options,
+		tagLookup: buildTagLookup(api)
+	});
+	const tags = tagsFromApi(api);
+	if (tags.length > 0) renderer("json").tags = tags;
+	return renderer;
+}
+/**
+* Generate an OpenAPI 3.1.0 document from an api. Returns a renderer: call
+* it with `'json'` or `'yaml'`. Options come from the `openApiPlugin` installed
+* on the api, so the document matches the one the server serves.
+*
+* Pass `overrides` for what only a build step knows, such as the public
+* `servers` list.
+*/
+function generateOpenApi(api, overrides) {
+	const options = optionsFromInstalledPlugin(api);
+	return renderOpenApi(api, overrides ? {
+		...options,
+		...overrides
+	} : options);
+}
+//#endregion
+//#region src/docs-html.ts
+const SCALAR_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1";
+const SWAGGER_CDN = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5";
+const escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/**
+* JSON for embedding in an inline `<script>`. Escaping `<` keeps a `<\/script>`
+* inside a config string from closing the tag early.
+*/
+const embedJson = (value) => JSON.stringify(value, null, 4).replace(/</g, "\\u003c").split("\n").join("\n            ");
+const scalarPage = (title, cdnUrl, configuration) => `<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>${escapeHtml(title)}</title>
+    </head>
+    <body>
+        <div id="app"></div>
+        <script src="${escapeHtml(cdnUrl)}"><\/script>
+        <script>
+            Scalar.createApiReference('#app', ${embedJson(configuration)});
+        <\/script>
+    </body>
+</html>
+`;
+const swaggerPage = (title, cdnUrl, configuration) => {
+	const base = cdnUrl.replace(/\/$/, "");
+	return `<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>${escapeHtml(title)}</title>
+        <link rel="stylesheet" href="${escapeHtml(base)}/swagger-ui.css" />
+    </head>
+    <body>
+        <div id="app"></div>
+        <script src="${escapeHtml(base)}/swagger-ui-bundle.js"><\/script>
+        <script>
+            SwaggerUIBundle(${embedJson(configuration)});
+        <\/script>
+    </body>
+</html>
+`;
+};
+/**
+* Render a self-contained page that loads an API reference UI over your OpenAPI
+* document. `openApiPlugin` calls this, so reach for it directly only when
+* kizuna has no adapter for your framework.
+*
+* @example
+* ```ts
+* const html = renderDocsHtml({
+*     specUrl: '/openapi.json',
+*     pageTitle: 'My API',
+* });
+* ```
+*/
+const renderDocsHtml = (options) => {
+	const title = options.pageTitle ?? "API Reference";
+	if ((options.provider ?? "scalar") === "swagger") return swaggerPage(title, options.cdnUrl ?? SWAGGER_CDN, {
+		dom_id: "#app",
+		...options.specUrl ? { url: options.specUrl } : { spec: options.specContent },
+		...options.configuration
+	});
+	return scalarPage(title, options.cdnUrl ?? SCALAR_CDN, {
+		...options.specUrl ? { url: options.specUrl } : { content: options.specContent },
+		...options.configuration
+	});
+};
+//#endregion
+//#region src/document-target.ts
+/**
+* An OpenAPI document target for `kizuna.config.ts`.
+*
+* @example
+* openApiDocument({ output: './openapi.yaml' });
+*/
+const openApiDocument = ({ output, ...overrides }) => ({
+	kind: "openapi",
+	output,
+	generate: (contract) => {
+		const render = generateOpenApi(contract, overrides);
+		return output.endsWith(".json") ? `${JSON.stringify(render("json"), null, 4)}\n` : render("yaml");
+	}
+});
+//#endregion
+//#region src/server.ts
+const HTML = "text/html; charset=utf-8";
+const JSON_TYPE = "application/json";
+const YAML = "text/yaml; charset=utf-8";
+const sent = (body, contentType) => new Response(body, {
+	status: 200,
+	headers: { "content-type": contentType }
+});
+/**
+* What answers the routes `openApiPlugin` declares: the reference UI, and the
+* document itself where the declaration published it.
+*/
+const openApiServe = (props, api) => {
+	const spec = renderOpenApi((0, kizunajs_adapter.contractOf)(api), props);
+	return { router: {
+		page: () => (0, kizunajs_adapter.rawResponse)(sent(renderDocsHtml({
+			specUrl: props.jsonPath,
+			specContent: props.jsonPath === void 0 ? spec("json") : void 0,
+			provider: props.provider,
+			pageTitle: props.pageTitle ?? spec("json").info.title,
+			cdnUrl: props.cdnUrl,
+			configuration: props.configuration
+		}), HTML)),
+		json: () => (0, kizunajs_adapter.rawResponse)(sent(JSON.stringify(spec("json")), JSON_TYPE)),
+		yaml: () => (0, kizunajs_adapter.rawResponse)(sent(spec("yaml"), YAML))
+	} };
+};
+/**
+* Serve an API reference UI for the OpenAPI document, and the document itself
+* if you publish it.
+*
+* The routes are public. Gate them with your framework's own middleware if that
+* is not what you want.
+*
+* @example
+* ```ts
+* export default defineConfig({
+*     routes,
+*     plugins: [
+*         openApiPlugin({
+*             info: {
+*                 title: 'My API',
+*                 version: '1.0.0',
+*             },
+*         }),
+*     ],
+* });
+* ```
+*/
+const declare = (slug, props) => (0, kizunajs_plugin.createPlugin)({
+	slug,
+	routes: {
+		...props.docsPath === void 0 ? {} : { page: {
+			method: "GET",
+			path: props.docsPath,
+			summary: "API reference",
+			responses: { 200: zod.z.string() }
+		} },
+		...props.jsonPath === void 0 ? {} : { json: {
+			method: "GET",
+			path: props.jsonPath,
+			summary: "OpenAPI document",
+			responses: { 200: zod.z.unknown() }
+		} },
+		...props.yamlPath === void 0 ? {} : { yaml: {
+			method: "GET",
+			path: props.yamlPath,
+			summary: "OpenAPI document, as YAML",
+			responses: { 200: zod.z.string() }
+		} }
+	},
+	props,
+	serve: (pluginProps, api) => openApiServe(pluginProps, api)
+});
+function openApiPlugin(props) {
+	return declare(props.slug ?? "openApi", props);
+}
+//#endregion
+exports.generateOpenApi = generateOpenApi;
+exports.openApiDocument = openApiDocument;
+exports.openApiPlugin = openApiPlugin;
+exports.renderDocsHtml = renderDocsHtml;
+exports.renderOpenApi = renderOpenApi;