@kizunajs/openapi 2.0.0-beta.10 → 2.0.0-beta.11

package/dist/index.d.mts

@@ -1,67 +1,9 @@
 import { z } from "zod";
-import { RoutePath, WithSlug } from "kizunajs/plugin";
+import { RoutePath } from "kizunajs/plugin";
 import { RouteDefinition } from "kizunajs/generator";
 import * as _$kizunajs from "kizunajs";
-import { ApiDefinition, ClientTarget } from "kizunajs";
+import { ApiDefinition } from "kizunajs";
 
-//#region src/docs-html.d.ts
-/**
- * The API reference UI rendered by the docs endpoint.
- */
-type DocsProvider = 'scalar' | 'swagger';
-interface DocsHtmlOptions {
-  /**
-   * URL the UI fetches the OpenAPI document from. Omit it and pass
-   * {@link DocsHtmlOptions.specContent} instead.
-   */
-  specUrl?: string;
-  /**
-   * The document itself, embedded in the page rather than fetched.
-   */
-  specContent?: unknown;
-  /**
-   * Which API reference UI to render.
-   *
-   * @default 'scalar'
-   */
-  provider?: DocsProvider;
-  /**
-   * The page's `<title>`.
-   *
-   * @default 'API Reference'
-   */
-  pageTitle?: string;
-  /**
-   * Where to load the UI's assets from. Point this at a self-hosted copy for
-   * air-gapped deployments or a strict CSP.
-   *
-   * For `'scalar'` this is the script URL. For `'swagger'` it is the
-   * directory holding `swagger-ui.css` and `swagger-ui-bundle.js`.
-   *
-   * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1' | 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5'
-   */
-  cdnUrl?: string;
-  /**
-   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`. See the
-   * provider's own documentation for the available keys.
-   */
-  configuration?: Record<string, unknown>;
-}
-/**
- * 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',
- * });
- * ```
- */
-declare const renderDocsHtml: (options: DocsHtmlOptions) => string;
-//#endregion
 //#region src/types.d.ts
 /**
  * The OpenAPI Specification version declared in the document's `openapi` field.
@@ -145,126 +87,214 @@ interface OpenApiDocument {
     schemas?: Record<string, unknown>;
   };
 }
-interface GenerateOpenApiOptions {
-  /**
-   * The OpenAPI Specification version to declare in the document's `openapi` field.
-   *
-   * Defaults to `'3.1.0'`.
-   */
-  openApiVersion?: OpenApiVersion;
-  info: OpenApiInfo;
-  servers?: OpenApiServer[];
-  externalDocs?: OpenApiExternalDocs;
-  setOperationId?: boolean | 'concatenated-path';
-  operationMapper?: (operation: OpenApiOperation, route: RouteDefinition, operationId: string) => OpenApiOperation;
-  /**
-   * Document the derived `head` operation on every `GET` path without a declared one.
-   *
-   * @default false
-   */
-  derivedHead?: boolean;
-}
+declare const GenerateOpenApiOptionsSchema: z.ZodObject<{
+  openApiVersion: z.ZodOptional<z.ZodLiteral<"3.1.0">>;
+  info: z.ZodObject<{
+    title: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  externalDocs: z.ZodOptional<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  setOperationId: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"concatenated-path">]>>;
+  includeHidden: z.ZodOptional<z.ZodBoolean>;
+  operationMapper: z.ZodOptional<z.ZodCustom<(operation: OpenApiOperation, route: RouteDefinition, operationId: string) => OpenApiOperation, (operation: OpenApiOperation, route: RouteDefinition, operationId: string) => OpenApiOperation>>;
+  derivedHead: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type GenerateOpenApiOptions = z.output<typeof GenerateOpenApiOptionsSchema>;
 interface OpenApiRenderer {
   (format: 'json'): OpenApiDocument;
   (format: 'yaml'): string;
 }
 //#endregion
 //#region src/plugin.d.ts
-declare const OPENAPI_PLUGIN_SLUG = "openApi";
 type JsonDocumentPath = `${RoutePath}.json`;
 type YamlDocumentPath = `${RoutePath}.yaml`;
-interface OpenApiPluginProps<Slug extends string = typeof OPENAPI_PLUGIN_SLUG> extends GenerateOpenApiOptions {
-  /**
-   * What handlers reach this plugin under. Give a second document its own.
-   *
-   * @default 'openApi'
-   */
-  slug?: Slug;
-  /**
-   * Where the reference UI is served.
-   */
-  docsPath?: RoutePath;
+declare const OpenApiPluginOptionsSchema: z.ZodObject<{
+  openApiVersion: z.ZodOptional<z.ZodLiteral<"3.1.0">>;
+  info: z.ZodObject<{
+    title: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  externalDocs: z.ZodOptional<z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  setOperationId: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"concatenated-path">]>>;
+  includeHidden: z.ZodOptional<z.ZodBoolean>;
+  operationMapper: z.ZodOptional<z.ZodCustom<(operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation, (operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation>>;
+  derivedHead: z.ZodOptional<z.ZodBoolean>;
+  output: z.ZodOptional<z.ZodString>;
+  docsPath: z.ZodOptional<z.ZodCustom<`/${string}`, `/${string}`>>;
+  jsonPath: z.ZodOptional<z.ZodCustom<`/${string}.json`, `/${string}.json`>>;
+  yamlPath: z.ZodOptional<z.ZodCustom<`/${string}.yaml`, `/${string}.yaml`>>;
+  provider: z.ZodOptional<z.ZodEnum<{
+    scalar: "scalar";
+    swagger: "swagger";
+  }>>;
+  cdnUrl: z.ZodOptional<z.ZodString>;
+  pageTitle: z.ZodOptional<z.ZodString>;
+  configuration: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type OpenApiPluginProps = z.output<typeof OpenApiPluginOptionsSchema>;
+/**
+ * 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',
+ *             },
+ *             docsPath: '/docs',
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+declare const openApiPlugin: {
+  <const Slug extends string>(options: {
+    info: {
+      title: string;
+      version: string;
+      description?: string | undefined;
+    };
+    openApiVersion?: "3.1.0" | undefined;
+    servers?: {
+      url: string;
+      description?: string | undefined;
+    }[] | undefined;
+    externalDocs?: {
+      url: string;
+      description?: string | undefined;
+    } | undefined;
+    setOperationId?: boolean | "concatenated-path" | undefined;
+    includeHidden?: boolean | undefined;
+    operationMapper?: ((operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation) | undefined;
+    derivedHead?: boolean | undefined;
+    output?: string | undefined;
+    docsPath?: `/${string}` | undefined;
+    jsonPath?: `/${string}.json` | undefined;
+    yamlPath?: `/${string}.yaml` | undefined;
+    provider?: "scalar" | "swagger" | undefined;
+    cdnUrl?: string | undefined;
+    pageTitle?: string | undefined;
+    configuration?: Record<string, unknown> | undefined;
+  } & {
+    slug: Slug;
+  }): _$kizunajs.PluginDeclaration<Slug, {
+    routes: _$kizunajs.PluginRoutes;
+    generators: _$kizunajs.GeneratedFile[];
+  }>;
+  (options: {
+    info: {
+      title: string;
+      version: string;
+      description?: string | undefined;
+    };
+    openApiVersion?: "3.1.0" | undefined;
+    servers?: {
+      url: string;
+      description?: string | undefined;
+    }[] | undefined;
+    externalDocs?: {
+      url: string;
+      description?: string | undefined;
+    } | undefined;
+    setOperationId?: boolean | "concatenated-path" | undefined;
+    includeHidden?: boolean | undefined;
+    operationMapper?: ((operation: OpenApiOperation, route: _$kizunajs.RouteDefinition, operationId: string) => OpenApiOperation) | undefined;
+    derivedHead?: boolean | undefined;
+    output?: string | undefined;
+    docsPath?: `/${string}` | undefined;
+    jsonPath?: `/${string}.json` | undefined;
+    yamlPath?: `/${string}.yaml` | undefined;
+    provider?: "scalar" | "swagger" | undefined;
+    cdnUrl?: string | undefined;
+    pageTitle?: string | undefined;
+    configuration?: Record<string, unknown> | undefined;
+  }): _$kizunajs.PluginDeclaration<"openApi", {
+    routes: _$kizunajs.PluginRoutes;
+    generators: _$kizunajs.GeneratedFile[];
+  }>;
+};
+//#endregion
+//#region src/docs-html.d.ts
+/**
+ * The API reference UI rendered by the docs endpoint.
+ */
+type DocsProvider = 'scalar' | 'swagger';
+interface DocsHtmlOptions {
   /**
-   * Where the document is served. The UI embeds it, so this is only for
-   * publishing the file.
+   * URL the UI fetches the OpenAPI document from. Omit it and pass
+   * {@link DocsHtmlOptions.specContent} instead.
    */
-  jsonPath?: JsonDocumentPath;
+  specUrl?: string;
   /**
-   * Where the document is served as YAML.
+   * The document itself, embedded in the page rather than fetched.
    */
-  yamlPath?: YamlDocumentPath;
+  specContent?: unknown;
   /**
    * Which API reference UI to render.
    *
    * @default 'scalar'
    */
   provider?: DocsProvider;
-  /**
-   * Where to load the UI's assets from, for a self-hosted copy. The script
-   * URL for `'scalar'`; the directory holding `swagger-ui.css` and
-   * `swagger-ui-bundle.js` for `'swagger'`.
-   */
-  cdnUrl?: string;
   /**
    * The page's `<title>`.
    *
-   * @default the document's `info.title`
+   * @default 'API Reference'
    */
   pageTitle?: string;
   /**
-   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`.
+   * Where to load the UI's assets from. Point this at a self-hosted copy for
+   * air-gapped deployments or a strict CSP.
+   *
+   * For `'scalar'` this is the script URL. For `'swagger'` it is the
+   * directory holding `swagger-ui.css` and `swagger-ui-bundle.js`.
+   *
+   * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1' | 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5'
+   */
+  cdnUrl?: string;
+  /**
+   * Merged into `Scalar.createApiReference` or `SwaggerUIBundle`. See the
+   * provider's own documentation for the available keys.
    */
   configuration?: Record<string, unknown>;
 }
 /**
- * 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.
+ * 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
- * export default defineConfig({
- *     routes,
- *     plugins: [
- *         openApiPlugin({
- *             info: {
- *                 title: 'My API',
- *                 version: '1.0.0',
- *             },
- *         }),
- *     ],
+ * const html = renderDocsHtml({
+ *     specUrl: '/openapi.json',
+ *     pageTitle: 'My API',
  * });
  * ```
  */
-declare const declare: (slug: string, props: OpenApiPluginProps<string>) => _$kizunajs.PluginDeclaration<{
-  readonly yaml?: {
-    readonly method: "GET";
-    readonly path: `/${string}.yaml`;
-    readonly summary: "OpenAPI document, as YAML";
-    readonly responses: {
-      readonly 200: z.ZodString;
-    };
-  } | undefined;
-  readonly json?: {
-    readonly method: "GET";
-    readonly path: `/${string}.json`;
-    readonly summary: "OpenAPI document";
-    readonly responses: {
-      readonly 200: z.ZodUnknown;
-    };
-  } | undefined;
-  readonly page?: {
-    readonly method: "GET";
-    readonly path: `/${string}`;
-    readonly summary: "API reference";
-    readonly responses: {
-      readonly 200: z.ZodString;
-    };
-  } | undefined;
-}, OpenApiPluginProps<string>, undefined, string, unknown>;
-declare function openApiPlugin<const Slug extends string = typeof OPENAPI_PLUGIN_SLUG>(props: OpenApiPluginProps<Slug>): WithSlug<ReturnType<typeof declare>, Slug>;
+declare const renderDocsHtml: (options: DocsHtmlOptions) => string;
 //#endregion
 //#region src/generator.d.ts
 /**
@@ -281,26 +311,4 @@ declare function renderOpenApi(api: ApiDefinition, options: GenerateOpenApiOptio
  */
 declare function generateOpenApi(api: ApiDefinition, overrides?: Partial<GenerateOpenApiOptions>): OpenApiRenderer;
 //#endregion
-//#region src/document-target.d.ts
-/**
- * Where the generated OpenAPI document is written. The format follows the
- * output extension: `.json` renders JSON, anything else renders YAML.
- */
-interface OpenApiDocumentOptions extends Partial<GenerateOpenApiOptions> {
-  /**
-   * Path the generated document is written to.
-   */
-  output: string;
-}
-/**
- * An OpenAPI document target for `kizuna.config.ts`.
- *
- * @example
- * openApiDocument({ output: './openapi.yaml' });
- */
-declare const openApiDocument: ({
-  output,
-  ...overrides
-}: OpenApiDocumentOptions) => ClientTarget;
-//#endregion
-export { type DocsHtmlOptions, type DocsProvider, type GenerateOpenApiOptions, type JsonDocumentPath, type OpenApiDocument, type OpenApiDocumentOptions, type OpenApiInfo, type OpenApiOperation, type OpenApiParameter, type OpenApiPluginProps, type OpenApiRenderer, type OpenApiResponseObject, type OpenApiServer, type OpenApiTag, type OpenApiVersion, type YamlDocumentPath, generateOpenApi, openApiDocument, openApiPlugin, renderDocsHtml, renderOpenApi };
+export { type DocsHtmlOptions, type DocsProvider, type GenerateOpenApiOptions, type JsonDocumentPath, type OpenApiDocument, type OpenApiInfo, type OpenApiOperation, type OpenApiParameter, type OpenApiPluginProps, type OpenApiRenderer, type OpenApiResponseObject, type OpenApiServer, type OpenApiTag, type OpenApiVersion, type YamlDocumentPath, generateOpenApi, openApiPlugin, renderDocsHtml, renderOpenApi };

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { createPlugin } from "kizunajs/plugin";
+import { RoutePathSchema, definePlugin, route } from "kizunajs/plugin";
+import { cacheHeaders, defineGenerator, deprecationHeaders, globalRegistrySchemas, isBinarySchema, isFileSchema, isNamedStream, isStreamResponse, isVoidSchema, parsePath, readDef, readDiscriminatedUnion, readDiscriminatorLiteral, readMeta, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, streamContentType, streamMode, walkApi } from "kizunajs/generator";
 import { contractOf, rawResponse } from "kizunajs/adapter";
 import { stringify } from "yaml";
-import { cacheHeaders, createGenerator, deprecationHeaders, globalRegistrySchemas, isBinarySchema, isFileSchema, isNamedStream, isStreamResponse, isVoidSchema, parsePath, readDef, readDiscriminatedUnion, readDiscriminatorLiteral, readMeta, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, streamContentType, streamMode } from "kizunajs/generator";
 import { getStatusText } from "kizunajs";
 //#region src/generator.ts
 const streamJsonSchema = (response, toJsonSchema) => {
@@ -161,10 +161,11 @@ const deriveHeadOperation = (getOperation) => {
 	for (const response of Object.values(operation.responses)) delete response.content;
 	return operation;
 };
-const openApiGenerator = createGenerator((options, api) => {
+const openApiWalk = (options, api) => {
 	const paths = {};
 	return {
-		processRoute({ routeKey, route, routeTags, deprecated }) {
+		processRoute({ routeKey, route, routeTags, deprecated, hidden }) {
+			if (hidden && options.includeHidden !== true) return;
 			const openApiPath = convertPath(route.path);
 			const method = route.method.toLowerCase();
 			let operation = {
@@ -378,7 +379,7 @@ const openApiGenerator = createGenerator((options, api) => {
 			return renderer;
 		}
 	};
-});
+};
 /**
 * The permissions a route requires, as `x-kizuna-requires`: what is acted on,
 * mapped to the verbs the caller has to hold.
@@ -458,17 +459,17 @@ const tagsFromApi = (api) => {
 * 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;
+	for (const plugin of Object.values(api.plugins ?? {})) if (plugin.definedSlug === "openApi") return plugin.options;
 	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, {
+	const renderer = walkApi(api, openApiWalk({
 		...options,
 		tagLookup: buildTagLookup(api)
-	});
+	}, api));
 	const tags = tagsFromApi(api);
 	if (tags.length > 0) renderer("json").tags = tags;
 	return renderer;
@@ -560,22 +561,6 @@ const renderDocsHtml = (options) => {
 	});
 };
 //#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";
@@ -585,23 +570,43 @@ const sent = (body, contentType) => new Response(body, {
 	headers: { "content-type": contentType }
 });
 /**
-* What answers the routes `openApiPlugin` declares: the reference UI, and the
-* document itself where the declaration published it.
+* The routes `openApiPlugin` serves: the reference UI, and the document itself
+* where the options publish it. The document is rendered on the first request,
+* once the api it describes has assembled.
 */
-const openApiServe = (props, api) => {
-	const spec = renderOpenApi(contractOf(api), props);
-	return { router: {
-		page: () => 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: () => rawResponse(sent(JSON.stringify(spec("json")), JSON_TYPE)),
-		yaml: () => rawResponse(sent(spec("yaml"), YAML))
-	} };
+const openApiRoutes = (props, api) => {
+	let renderer;
+	const spec = ((format) => {
+		renderer ??= renderOpenApi(contractOf(api), props);
+		return renderer(format);
+	});
+	const routes = {};
+	if (props.docsPath !== void 0) routes.page = route({
+		method: "GET",
+		path: props.docsPath,
+		summary: "API reference",
+		responses: { 200: z.string() }
+	}).handler(() => 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)));
+	if (props.jsonPath !== void 0) routes.json = route({
+		method: "GET",
+		path: props.jsonPath,
+		summary: "OpenAPI document",
+		responses: { 200: z.unknown() }
+	}).handler(() => rawResponse(sent(JSON.stringify(spec("json")), JSON_TYPE)));
+	if (props.yamlPath !== void 0) routes.yaml = route({
+		method: "GET",
+		path: props.yamlPath,
+		summary: "OpenAPI document, as YAML",
+		responses: { 200: z.string() }
+	}).handler(() => rawResponse(sent(spec("yaml"), YAML)));
+	return routes;
 };
 /**
 * Serve an API reference UI for the OpenAPI document, and the document itself
@@ -620,38 +625,117 @@ const openApiServe = (props, api) => {
 *                 title: 'My API',
 *                 version: '1.0.0',
 *             },
+*             docsPath: '/docs',
 *         }),
 *     ],
 * });
 * ```
 */
-const declare = (slug, props) => createPlugin({
-	slug,
-	routes: {
-		...props.docsPath === void 0 ? {} : { page: {
-			method: "GET",
-			path: props.docsPath,
-			summary: "API reference",
-			responses: { 200: z.string() }
-		} },
-		...props.jsonPath === void 0 ? {} : { json: {
-			method: "GET",
-			path: props.jsonPath,
-			summary: "OpenAPI document",
-			responses: { 200: z.unknown() }
-		} },
-		...props.yamlPath === void 0 ? {} : { yaml: {
-			method: "GET",
-			path: props.yamlPath,
-			summary: "OpenAPI document, as YAML",
-			responses: { 200: z.string() }
-		} }
-	},
-	props,
-	serve: (pluginProps, api) => openApiServe(pluginProps, api)
+const openApiPlugin = definePlugin({
+	slug: "openApi",
+	options: z.object({
+		/**
+		* The OpenAPI Specification version to declare in the document's `openapi` field.
+		*
+		* Defaults to `'3.1.0'`.
+		*/
+		openApiVersion: z.literal("3.1.0").optional(),
+		info: z.object({
+			title: z.string(),
+			version: z.string(),
+			description: z.string().optional()
+		}),
+		servers: z.array(z.object({
+			url: z.string(),
+			description: z.string().optional()
+		})).optional(),
+		externalDocs: z.object({
+			url: z.string(),
+			description: z.string().optional()
+		}).optional(),
+		setOperationId: z.union([z.boolean(), z.literal("concatenated-path")]).optional(),
+		/**
+		* Document `hidden` routes too, for a document your own team reads.
+		*
+		* @default false
+		*/
+		includeHidden: z.boolean().optional(),
+		operationMapper: z.custom((value) => typeof value === "function", { error: "must be a function" }).optional(),
+		/**
+		* Document the derived `head` operation on every `GET` path without a declared one.
+		*
+		* @default false
+		*/
+		derivedHead: z.boolean().optional()
+	}).extend({
+		/**
+		* Where `kizuna generate` writes the document. `.json` renders JSON,
+		* anything else YAML.
+		*
+		* @example
+		* output: './openapi.yaml',
+		*/
+		output: z.string().optional(),
+		/**
+		* Where the reference UI is served.
+		*/
+		docsPath: RoutePathSchema.optional(),
+		/**
+		* Where the document is served. The UI embeds it, so this is only for
+		* publishing the file.
+		*/
+		jsonPath: z.custom((value) => typeof value === "string" && value.startsWith("/") && value.endsWith(".json"), { error: "must start with / and end in .json" }).optional(),
+		/**
+		* Where the document is served as YAML.
+		*/
+		yamlPath: z.custom((value) => typeof value === "string" && value.startsWith("/") && value.endsWith(".yaml"), { error: "must start with / and end in .yaml" }).optional(),
+		/**
+		* Which API reference UI to render.
+		*
+		* @default 'scalar'
+		*/
+		provider: z.enum(["scalar", "swagger"]).optional(),
+		/**
+		* Where to load the UI's assets from, for a self-hosted copy. The script
+		* URL for `'scalar'`; the directory holding `swagger-ui.css` and
+		* `swagger-ui-bundle.js` for `'swagger'`.
+		*/
+		cdnUrl: z.string().optional(),
+		/**
+		* The page's `<title>`.
+		*
+		* @default the document's `info.title`
+		*/
+		pageTitle: z.string().optional(),
+		/**
+		* Merged into `Scalar.createApiReference` or `SwaggerUIBundle`.
+		*/
+		configuration: z.record(z.string(), z.unknown()).optional()
+	}),
+	setup: ({ options, api }) => {
+		const { output, ...document } = options;
+		return {
+			routes: openApiRoutes(options, api),
+			generators: output === void 0 ? [] : [openApiDocumentGenerator({
+				output,
+				json: output.endsWith(".json"),
+				document
+			})]
+		};
+	}
+});
+/**
+* Writes one document, in the format its `output` names.
+*/
+const openApiDocumentGenerator = defineGenerator({
+	options: z.object({
+		json: z.boolean(),
+		document: z.custom()
+	}),
+	generate: ({ options, api }) => ({ finalize: () => {
+		const render = renderOpenApi(api, options.document);
+		return options.json ? `${JSON.stringify(render("json"), null, 4)}\n` : render("yaml");
+	} })
 });
-function openApiPlugin(props) {
-	return declare(props.slug ?? "openApi", props);
-}
 //#endregion
-export { generateOpenApi, openApiDocument, openApiPlugin, renderDocsHtml, renderOpenApi };
+export { generateOpenApi, openApiPlugin, renderDocsHtml, renderOpenApi };