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

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, 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) => {
@@ -79,12 +79,25 @@ const buildDiscriminatorBlock = (propertyName, options) => {
 	} : { propertyName };
 };
 /**
+* What the wire carries for a type JSON Schema has no keyword for, which
+* `unrepresentable: 'any'` would otherwise leave as an empty schema.
+*/
+const JSON_ENCODING = {
+	date: {
+		type: "string",
+		format: "date-time"
+	},
+	bigint: { type: "string" }
+};
+/**
 * 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 }) => {
+const normalizeMeta = ({ zodSchema, jsonSchema }) => {
+	const encoding = JSON_ENCODING[readDef(zodSchema).type ?? ""];
+	if (encoding && Object.keys(jsonSchema).length === 0) Object.assign(jsonSchema, encoding);
 	if (typeof jsonSchema.deprecated === "string") jsonSchema.deprecated = true;
 	if ("example" in jsonSchema) {
 		const given = Array.isArray(jsonSchema.example) ? jsonSchema.example : [jsonSchema.example];
@@ -148,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 = {
@@ -365,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.
@@ -445,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;
@@ -547,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";
@@ -572,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
@@ -607,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kizunajs/openapi",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.11",
   "description": "OpenAPI 3.1 generation for Kizuna.js APIs",
   "keywords": [
     "kizunajs",
@@ -60,7 +60,7 @@
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.1"
+    "kizunajs": "2.0.0-beta.11"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
@@ -68,8 +68,8 @@
     "tsdown": "^0.21.0",
     "typescript": "^6.0.3",
     "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.1",
-    "@kizunajs/express": "2.0.0-beta.1"
+    "@kizunajs/express": "2.0.0-beta.11",
+    "kizunajs": "2.0.0-beta.11"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts --clean --external kizunajs --external zod",