nitro-openapi-schemas 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oumar Barry
+
+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,184 @@
+# nitro-openapi-schemas
+
+[![CI](https://github.com/oumarbarry/nitro-openapi-schemas/actions/workflows/ci.yml/badge.svg?branch=nitro-v2)](https://github.com/oumarbarry/nitro-openapi-schemas/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/nitro-openapi-schemas/nitro-v2?color=yellow)](https://npmjs.com/package/nitro-openapi-schemas/v/nitro-v2)
+[![license](https://img.shields.io/npm/l/nitro-openapi-schemas?color=yellow)](https://github.com/oumarbarry/nitro-openapi-schemas/blob/main/LICENSE)
+
+Schema-driven OpenAPI for [Nitro](https://nitro.build). The Zod, Valibot or
+ArkType schema that validates a route at runtime also documents it: every
+handler with `validate` schemas or `meta.openAPI` ends up in `/_openapi.json`,
+with a Scalar UI at `/_scalar`. Nothing is declared twice and nothing is
+extracted from source at build time.
+
+```
+Zod / Valibot / ArkType schema
+  → defineValidatedHandler   validates the request
+  → /_openapi.json           OpenAPI 3.1, generated from the same schemas
+  → openapi.json             written after `nitro build`, ready for SDK codegen
+```
+
+- This is the Nitro v2 and Nuxt 4 line: `nitropack` 2.x and h3 1.x, published
+  as 2.x under the `nitro-v2` dist-tag from the branch of the same name. Nitro v3 users
+  want the [`main` branch](https://github.com/oumarbarry/nitro-openapi-schemas/tree/main) and the `latest` tag.
+- Zod 4.2+, ArkType 2.1.28+, and Valibot through `@valibot/to-json-schema`
+  1.5+, via [Standard JSON Schema](https://github.com/standard-schema/standard-schema/pull/134).
+  Bring the one you use; none is installed for you.
+- Named schemas become `components/schemas` entries, emitted once and
+  referenced by `$ref` wherever they appear.
+
+## Install
+
+```sh
+bun add nitro-openapi-schemas@nitro-v2   # or npm, pnpm
+```
+
+## Usage
+
+Register the module and, optionally, the `info` block of the spec:
+
+```ts
+// nitro.config.ts
+import { defineNitroConfig } from "nitropack/config";
+import openAPISchemas from "nitro-openapi-schemas";
+
+export default defineNitroConfig({
+  modules: [openAPISchemas],
+  openAPISchemas: {
+    info: { title: "Payments API", version: "1.0.0" },
+    // route: "/_openapi.json",  // default
+    // scalar: true,             // default, Scalar UI at /_scalar
+  },
+});
+```
+
+```ts
+// nuxt.config.ts (Nuxt 4): same options, nested under `nitro`
+import openAPISchemas from "nitro-openapi-schemas";
+
+export default defineNuxtConfig({
+  nitro: {
+    modules: [openAPISchemas],
+    openAPISchemas: { info: { title: "Payments API", version: "1.0.0" } },
+  },
+});
+```
+
+Then write routes with `defineValidatedHandler` from `nitro-openapi-schemas/h3`.
+It validates `query`, `headers` and `body` through each schema's own
+`~standard.validate` (400 with the issues in `data` on failure, body skipped
+for GET and HEAD) and documents them. `meta.openAPI` is merged into the
+operation, and a `schema` on a response is converted too:
+
+```ts
+// routes/api/payments/index.post.ts (Nuxt: server/api/payments/index.post.ts)
+import { readBody } from "h3";
+import { defineValidatedHandler } from "nitro-openapi-schemas/h3";
+import { createPaymentSchema, paymentSchema } from "../../shared/schema.ts";
+
+export default defineValidatedHandler({
+  validate: { body: createPaymentSchema },
+  meta: {
+    openAPI: {
+      tags: ["payments"],
+      summary: "Create a payment",
+      responses: { 200: { description: "Payment created", schema: paymentSchema } },
+    },
+  },
+  handler: async (event) => {
+    const body = await readBody(event); // already validated
+    // ...
+  },
+});
+```
+
+`readBody` returns the parsed body as it was sent, not the schema's output, so
+defaults and coercions declared in the schema are not applied to it. Start the
+server and open `/_scalar`, or fetch `/_openapi.json`. Path parameters are
+documented from the route pattern, so `defineValidatedHandler` with only `meta`
+is enough for a route without validation.
+
+### Naming components
+
+A schema with an id is hoisted into `components/schemas` under that id and
+referenced by `$ref` everywhere it appears, nested schemas included. Each
+library has its own way to set it:
+
+| Library | Named schema                                               |
+| ------- | ---------------------------------------------------------- |
+| Zod     | `z.object({ ... }).meta({ id: "Payment" })`                |
+| ArkType | `type({ ... }).configure({ id: "Payment" })`               |
+| Valibot | `v.pipe(v.object({ ... }), v.metadata({ id: "Payment" }))` |
+
+Anonymous schemas are inlined. A query or header schema is flattened into one
+parameter per property.
+
+### The spec as a build artifact
+
+The spec is generated at runtime from the handlers in the bundle, so getting it
+as a file means booting the built server once and saving the response.
+[examples/nitro/scripts/emit-openapi.mjs](examples/nitro/scripts/emit-openapi.mjs)
+does exactly that, and `openapi-typescript` turns the result into a typed
+client:
+
+```sh
+bun run openapi   # nitro build, boot the output, write openapi.json
+bun run sdk       # openapi-typescript openapi.json -o sdk.d.ts
+```
+
+## Nitro v3
+
+The `latest` dist-tag targets Nitro v3 and h3 v2, where `defineValidatedHandler`
+comes from `nitro/h3` itself. Install with `bun add nitro-openapi-schemas` and
+read the [`main` branch](https://github.com/oumarbarry/nitro-openapi-schemas) README.
+
+## How it works
+
+The module emits a virtual module that imports every scanned route handler
+directly, bypassing Nitro's lazy wrappers. `defineValidatedHandler` from
+`nitro-openapi-schemas/h3` assigns the `validate` schemas and `meta` onto the
+handler function, the same contract h3 v2 provides natively, so the spec route
+can read those live objects, convert each schema through `~standard.jsonSchema`
+(or wrap it with `@valibot/to-json-schema` when the library does not expose
+that yet), hoist named schemas and Zod's nested `$defs` into
+`components/schemas`, and cache the document after the first request.
+
+The trade-off: routes imported by the spec route are no longer lazy-loaded.
+Nuxt's catch-all renderer (`/**`) is left out of the import for that reason.
+
+## Limitations
+
+- JSON request bodies only. Cookie parameters and other content types are not
+  described.
+- One HTTP method per route file, as in Nitro's file routing.
+- Header parameter names are emitted as written in the schema, without case
+  normalization.
+- The document is cached after the first request. In dev, restart the server
+  after changing a schema in a route that was already loaded.
+- Response schemas go in `meta.openAPI.responses[status].schema`, since h3's
+  `validate` has no `response` field.
+
+## Background
+
+This module is the implementation behind
+[nitrojs/nitro#4402](https://github.com/nitrojs/nitro/discussions/4402), a
+proposal to generate OpenAPI from Standard Schema validators inside Nitro
+itself (see also [#2974](https://github.com/nitrojs/nitro/issues/2974) and
+[#3542](https://github.com/nitrojs/nitro/issues/3542)). Until that lands, it
+works as a standalone module.
+
+## Development
+
+```sh
+bun install && bun install --force   # the second install links the built dist/ into the examples
+bun run dev            # example app at http://localhost:3000/_scalar
+bun run check          # oxlint + oxfmt
+bun run build          # obuild, writes dist/
+bun run openapi        # end-to-end: build examples/nitro and write its openapi.json
+bun run openapi:nuxt4  # same for examples/nuxt4
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/dist/h3.d.mts

@@ -0,0 +1,36 @@
+import { EventHandler, EventHandlerObject, EventHandlerRequest, EventHandlerResponse } from "h3";
+interface StandardSchema {
+  "~standard": {
+    vendor: string;
+    version: number;
+    validate: (value: unknown) => {
+      value: unknown;
+      issues?: undefined;
+    } | {
+      issues: readonly unknown[];
+    } | Promise<{
+      value: unknown;
+      issues?: undefined;
+    } | {
+      issues: readonly unknown[];
+    }>;
+  };
+}
+interface ValidateSchemas {
+  body?: StandardSchema;
+  query?: StandardSchema;
+  headers?: StandardSchema;
+}
+interface HandlerMeta {
+  openAPI?: Record<string, any>;
+  [key: string]: unknown;
+}
+type ValidatedHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response = EventHandlerResponse> = EventHandler<Request, Response> & {
+  validate?: ValidateSchemas;
+  meta?: HandlerMeta;
+};
+declare function defineValidatedHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response = EventHandlerResponse>(def: EventHandlerObject<Request, Response> & {
+  validate?: ValidateSchemas;
+  meta?: HandlerMeta;
+}): ValidatedHandler<Request, Response>;
+export { HandlerMeta, ValidateSchemas, ValidatedHandler, defineValidatedHandler };

package/dist/h3.mjs

@@ -0,0 +1,27 @@
+import { createError, defineEventHandler, getQuery, getRequestHeaders, readBody } from "h3";
+function defineValidatedHandler(def) {
+	const { validate, meta } = def;
+	const handler = defineEventHandler({
+		...def,
+		handler: async (event) => {
+			if (validate?.query) await validatePart(validate.query, getQuery(event), "query");
+			if (validate?.headers) await validatePart(validate.headers, getRequestHeaders(event), "headers");
+			if (validate?.body && event.method !== "GET" && event.method !== "HEAD") await validatePart(validate.body, await readBody(event), "body");
+			return def.handler(event);
+		}
+	});
+	return Object.assign(handler, {
+		validate,
+		meta
+	});
+}
+async function validatePart(schema, value, part) {
+	const result = await schema["~standard"].validate(value);
+	if (result.issues) throw createError({
+		status: 400,
+		statusMessage: "Validation Error",
+		message: `Invalid ${part}`,
+		data: result.issues
+	});
+}
+export { defineValidatedHandler };

package/dist/index.d.mts

@@ -0,0 +1,32 @@
+import { NitroModule } from "nitropack/types";
+interface NitroOpenAPISchemasOptions {
+  /** Route serving the generated spec. Default: `/_openapi.json` */
+  route?: string;
+  /** Mount Nitro's Scalar UI at `/_scalar` on top of the spec. Default: true */
+  scalar?: boolean;
+  /** OpenAPI info object (title, version, description). */
+  info?: {
+    title?: string;
+    version?: string;
+    description?: string;
+  };
+}
+declare module "nitropack/types" {
+  interface NitroConfig {
+    openAPISchemas?: NitroOpenAPISchemasOptions;
+  }
+  interface NitroOptions {
+    openAPISchemas?: NitroOpenAPISchemasOptions;
+  }
+}
+/**
+ * Nitro v2 / Nuxt 4 line.
+ *
+ * Emits a virtual module that imports every scanned route handler *directly*
+ * (bypassing lazy wrappers), so the spec route can read the live `validate`
+ * schemas and `meta` attached to the handler function at runtime. h3 v1 has
+ * no defineValidatedHandler, so this package ships its own shim (see ./h3.ts)
+ * that attaches them.
+ */
+declare const nitroOpenAPISchemas: NitroModule;
+export { NitroOpenAPISchemasOptions, nitroOpenAPISchemas as default };

package/dist/index.mjs

@@ -0,0 +1,30 @@
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { runtimeDir } from "nitropack/runtime/meta";
+const nitroOpenAPISchemas = {
+	name: "nitro-openapi-schemas",
+	setup(nitro) {
+		const options = nitro.options.openAPISchemas || {};
+		const specRoute = options.route || "/_openapi.json";
+		nitro.options.virtual["#nitro-openapi-schemas"] = () => {
+			const entries = [...nitro.scannedHandlers, ...nitro.options.handlers].filter((h) => h.route && !h.middleware && h.route !== specRoute && !h.route.startsWith("/_") && !h.route.includes("**") && typeof h.handler === "string");
+			const files = [...new Set(entries.map((h) => h.handler))];
+			return [
+				...files.map((file, i) => `import h${i} from ${JSON.stringify(file)};`),
+				`export const config = ${JSON.stringify({ info: options.info })};`,
+				"export const routes = [",
+				...entries.map((h) => `  { route: ${JSON.stringify(h.route)}, method: ${JSON.stringify((h.method || "get").toLowerCase())}, handler: h${files.indexOf(h.handler)} },`),
+				"];"
+			].join("\n");
+		};
+		nitro.options.handlers.push({
+			route: specRoute,
+			handler: fileURLToPath(new URL("runtime/route", import.meta.url))
+		});
+		if (options.scalar !== false) nitro.options.handlers.push({
+			route: "/_scalar",
+			handler: join(runtimeDir, "internal/routes/scalar")
+		});
+	}
+};
+export { nitroOpenAPISchemas as default };

package/dist/runtime/generator.mjs

@@ -0,0 +1,190 @@
+export async function toOpenAPIDocument(entries, opts = {}) {
+	const registry = new SchemaRegistry();
+	const paths = {};
+	for (const entry of entries) {
+		const { route, parameters } = normalizeRoute(entry.route);
+		const { validate, meta } = entry.handler;
+		const { responses: metaResponses, ...openAPI } = meta?.openAPI || {};
+		if (validate?.query) {
+			parameters.push(...await schemaToParameters(registry, validate.query, "query"));
+		}
+		if (validate?.headers) {
+			parameters.push(...await schemaToParameters(registry, validate.headers, "header"));
+		}
+		const operation = {
+			...parameters.length > 0 ? { parameters } : {},
+			responses: { 200: { description: "OK" } },
+			...openAPI
+		};
+		if (validate?.body) {
+			operation.requestBody = {
+				required: true,
+				content: { "application/json": { schema: await registry.toJsonSchema(validate.body, "input") } }
+			};
+		}
+		if (metaResponses) {
+			operation.responses = {};
+			for (const [status, res] of Object.entries(metaResponses)) {
+				const { schema, ...rest } = res;
+				operation.responses[status] = isStandardSchema(schema) ? {
+					...rest,
+					content: { "application/json": { schema: await registry.toJsonSchema(schema, "output") } }
+				} : res;
+			}
+		}
+		(paths[route] ??= {})[entry.method] = operation;
+	}
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: "Nitro Server Routes",
+			version: "1.0.0",
+			...opts.info
+		},
+		servers: opts.servers,
+		paths,
+		...registry.hasComponents() ? { components: { schemas: registry.components } } : {}
+	};
+}
+
+function isStandardSchema(value) {
+	return !!value && typeof value === "object" && "~standard" in value;
+}
+
+class SchemaRegistry {
+	components = {};
+	
+	#seen = {
+		input: new Map(),
+		output: new Map()
+	};
+	hasComponents() {
+		return Object.keys(this.components).length > 0;
+	}
+	async toJsonSchema(schema, io) {
+		const seen = this.#seen[io];
+		const cached = seen.get(schema);
+		if (cached) return cached;
+		const { json, name } = await convert(schema, io);
+		
+		
+		if (json.$defs) {
+			for (const [defName, defSchema] of Object.entries(json.$defs)) {
+				this.components[defName] ??= rewriteDefsRefs(defSchema);
+			}
+			delete json.$defs;
+			rewriteDefsRefs(json);
+		}
+		let result = json;
+		if (name) {
+			
+			
+			const finalName = io === "input" && this.components[name] ? `${name}Input` : name;
+			this.components[finalName] = json;
+			result = { $ref: `#/components/schemas/${finalName}` };
+		}
+		seen.set(schema, result);
+		return result;
+	}
+}
+
+
+
+function schemaId(schema, vendor) {
+	switch (vendor) {
+		case "zod": {
+			return schema.meta?.()?.id;
+		}
+		case "arktype": {
+			return schema.meta?.id;
+		}
+		default: {
+			return undefined;
+		}
+	}
+}
+function rewriteDefsRefs(node) {
+	if (Array.isArray(node)) {
+		for (const item of node) rewriteDefsRefs(item);
+	} else if (node && typeof node === "object") {
+		if (typeof node.$ref === "string" && node.$ref.startsWith("#/$defs/")) {
+			node.$ref = node.$ref.replace("#/$defs/", "#/components/schemas/");
+		}
+		for (const value of Object.values(node)) rewriteDefsRefs(value);
+	}
+	return node;
+}
+async function convert(schema, io) {
+	const std = schema["~standard"];
+	
+	
+	
+	if (std.jsonSchema) {
+		const json = std.jsonSchema[io]({ target: "draft-2020-12" });
+		delete json.$schema;
+		return {
+			json,
+			name: schemaId(schema, std.vendor)
+		};
+	}
+	
+	
+	
+	const vendor = std.vendor;
+	switch (vendor) {
+		case "valibot": {
+			
+			
+			// @valibot/to-json-schema@1.5+ ships toStandardJsonSchema(), a
+			
+			
+			
+			
+			const { toStandardJsonSchema } = await import("@valibot/" + "to-json-schema");
+			const name = schema.pipe?.find((a) => a.kind === "metadata")?.metadata?.id;
+			const { json } = await convert(toStandardJsonSchema(schema), io);
+			return {
+				json,
+				name
+			};
+		}
+		case "arktype": {
+			return { json: schema.toJsonSchema() };
+		}
+		default: {
+			throw new Error(`[openapi] No JSON Schema converter for schema vendor "${vendor}". Supported: zod, valibot, arktype.`);
+		}
+	}
+}
+async function schemaToParameters(registry, schema, location) {
+	const json = await registry.toJsonSchema(schema, "input");
+	const resolved = json.$ref ? registry.components[json.$ref.split("/").pop()] : json;
+	if (resolved?.type !== "object" || !resolved.properties) return [];
+	return Object.entries(resolved.properties).map(([name, propSchema]) => ({
+		name,
+		in: location,
+		required: resolved.required?.includes(name) ?? false,
+		schema: propSchema
+	}));
+}
+
+function normalizeRoute(_route) {
+	const parameters = [];
+	let anonymousCtr = 0;
+	const route = _route.replace(/:(\w+)/g, (_, name) => `{${name}}`).replace(/\/(\*)\//g, () => `/{param${++anonymousCtr}}/`).replace(/\*\*{/, "{").replace(/\/(\*\*)$/g, () => `/{*param${++anonymousCtr}}`);
+	for (const match of route.matchAll(/{(\*?\w+)}/g)) {
+		const name = match[1];
+		if (!parameters.some((p) => p.name === name)) {
+			parameters.push({
+				name,
+				in: "path",
+				required: true,
+				schema: { type: "string" }
+			});
+		}
+	}
+	return {
+		route,
+		parameters
+	};
+}

package/dist/runtime/route.mjs

@@ -0,0 +1,13 @@
+import { defineEventHandler, getRequestURL } from "h3";
+// @ts-expect-error virtual module provided by ../index.ts
+import { routes, config } from "#nitro-openapi-schemas";
+import { toOpenAPIDocument } from "./generator.mjs";
+let cached;
+export default defineEventHandler((event) => {
+	
+	const origin = getRequestURL(event).origin;
+	return cached ??= toOpenAPIDocument(routes, {
+		info: config.info,
+		servers: [{ url: origin }]
+	});
+});

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "nitro-openapi-schemas",
+  "version": "2.0.0",
+  "description": "Schema-driven OpenAPI for Nitro: the Zod, Valibot or ArkType schema that validates a route also documents it",
+  "keywords": [
+    "api",
+    "arktype",
+    "h3",
+    "json-schema",
+    "nitro",
+    "nuxt",
+    "openapi",
+    "standard-schema",
+    "swagger",
+    "valibot",
+    "zod"
+  ],
+  "homepage": "https://github.com/oumarbarry/nitro-openapi-schemas#readme",
+  "bugs": "https://github.com/oumarbarry/nitro-openapi-schemas/issues",
+  "license": "MIT",
+  "author": "Oumar Barry",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oumarbarry/nitro-openapi-schemas.git"
+  },
+  "workspaces": [
+    "examples/*"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./h3": {
+      "types": "./dist/h3.d.mts",
+      "default": "./dist/h3.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run --cwd examples/nitro dev",
+    "openapi": "bun run --cwd examples/nitro openapi",
+    "openapi:nuxt4": "bun run --cwd examples/nuxt4 openapi",
+    "sdk": "bun run --cwd examples/nitro sdk",
+    "build": "obuild",
+    "prepare": "obuild",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "check": "oxlint && oxfmt --check",
+    "fix": "oxlint --fix && oxfmt"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "jiti": "^2.7.0",
+    "obuild": "^0.4.37",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@valibot/to-json-schema": "^1.5.0",
+    "arktype": "^2.1.28",
+    "h3": "^1.15.0",
+    "nitropack": "^2.12.0",
+    "zod": "^4.2.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    },
+    "arktype": {
+      "optional": true
+    },
+    "@valibot/to-json-schema": {
+      "optional": true
+    }
+  }
+}