@zudojs/openapi 1.3.0 → 1.5.0

package/dist/openApiRouting/routeContent.core.js

@@ -0,0 +1,101 @@
+/**
+ * Request body and response construction for route conversion.
+ *
+ * Both accept schemas as well as raw OpenAPI objects, so a route that
+ * declares `body: userSchema` documents exactly the payload it parses.
+ */
+import { HttpStatus } from "@zudojs/constants";
+import { isSchemaDefinition, resolveSchemaInput, } from "../openApiSchema/schemaInput.core.js";
+import { DEFAULT_MEDIA_TYPE, UNDOCUMENTED_RESPONSE_DESCRIPTION } from "../openApiConstants/openApiConstants.core.js";
+const REASON_PHRASES = new Map(Object.entries(HttpStatus).map(([name, code]) => [
+    String(code),
+    name
+        .toLowerCase()
+        .split("_")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" "),
+]));
+const RANGE_DESCRIPTIONS = {
+    "1XX": "Informational",
+    "2XX": "Success",
+    "3XX": "Redirection",
+    "4XX": "Client error",
+    "5XX": "Server error",
+    default: "Unexpected response",
+};
+/** A default description for a response key: `404` → "Not Found". */
+export function describeResponseKey(key) {
+    return REASON_PHRASES.get(key) ?? RANGE_DESCRIPTIONS[key] ?? `Response ${key}`;
+}
+function isDescriptorWithSchema(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !isSchemaDefinition(value) &&
+        Object.hasOwn(value, "schema"));
+}
+function mediaTypes(contentType, media) {
+    const types = contentType === undefined
+        ? [DEFAULT_MEDIA_TYPE]
+        : typeof contentType === "string" ? [contentType] : contentType;
+    return Object.fromEntries(types.map((type) => [type, media]));
+}
+/** Builds the Request Body Object from `requestBody` or `body`. */
+export function buildOperationRequestBody(meta, context, options = {}) {
+    if (meta?.requestBody)
+        return meta.requestBody;
+    if (meta?.body === undefined)
+        return undefined;
+    const body = isDescriptorWithSchema(meta.body)
+        ? meta.body
+        : { schema: meta.body };
+    const schema = resolveSchemaInput(body.schema, `${context} body`, options);
+    return {
+        ...(body.description ? { description: body.description } : {}),
+        required: body.required ?? true,
+        content: mediaTypes(body.contentType, {
+            schema,
+            ...(body.example !== undefined ? { example: body.example } : {}),
+        }),
+    };
+}
+function toResponse(key, entry, context, options) {
+    if (!isDescriptorWithSchema(entry))
+        return entry;
+    const response = entry;
+    const schema = resolveSchemaInput(response.schema, `${context} response ${key}`, options);
+    return {
+        description: response.description ?? describeResponseKey(key),
+        ...(response.headers ? { headers: response.headers } : {}),
+        content: mediaTypes(response.contentType, {
+            schema,
+            ...(response.example !== undefined ? { example: response.example } : {}),
+        }),
+    };
+}
+/**
+ * Builds the `responses` object for an operation.
+ *
+ * Every documented response is carried through; an entry with a `schema` is
+ * expanded into a Response Object. A route that documents none gets a
+ * `default` "Undocumented response" (`responses` is required) and a warning
+ * through `options.onWarning`. No status is invented.
+ */
+export function buildOperationResponses(meta, context, options = {}) {
+    const declared = meta?.responses;
+    if (!declared || Object.keys(declared).length === 0) {
+        options.onWarning?.(`${context}: no responses are documented; emitted "default: ${UNDOCUMENTED_RESPONSE_DESCRIPTION}".`);
+        const fallback = { description: UNDOCUMENTED_RESPONSE_DESCRIPTION };
+        return Object.freeze({ default: Object.freeze(fallback) });
+    }
+    const responses = {};
+    for (const [key, entry] of Object.entries(declared)) {
+        Object.defineProperty(responses, key, {
+            value: toResponse(key, entry, context, options),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return Object.freeze(responses);
+}
+//# sourceMappingURL=routeContent.core.js.map

package/dist/openApiRouting/routeConverter.core.d.ts

@@ -1,5 +1,5 @@
 import type { OpenAPIOperation, OpenAPIResponses } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPIHttpMethod, RouteMetadata } from "./routeMetadata.type.js";
+import type { OpenAPIHttpMethod, RouteConversionOptions, RouteMetadata } from "./routeMetadata.type.js";
 /**
  * Maps Zudojs HTTP methods to OpenAPI methods.
  */
@@ -26,14 +26,20 @@ export declare function extractPathParameters(path: string): readonly string[];
 /**
  * Builds the `responses` object for an operation.
  *
- * Every documented response is carried through. Only when a route documents
- * none at all is a `200` synthesized, because `responses` is required.
+ * Every documented response is carried through. A route that documents none
+ * gets a `default` "Undocumented response" and a warning through
+ * `options.onWarning`; no `200` is invented.
  */
-export declare function buildResponses(metadata?: RouteMetadata): OpenAPIResponses;
+export declare function buildResponses(metadata?: RouteMetadata, options?: RouteConversionOptions): OpenAPIResponses;
 /**
  * Converts a route with metadata into an OpenAPI operation.
+ *
+ * Every path template slot is documented as a required path parameter even
+ * when the route declares none; schemas declared as `params`, `query`,
+ * `headers`, `cookies`, `body` or response `schema` are converted for
+ * `options.version`.
  */
-export declare function convertRouteToOpenAPI(method: string, path: string, metadata?: RouteMetadata): {
+export declare function convertRouteToOpenAPI(method: string, path: string, metadata?: RouteMetadata, options?: RouteConversionOptions): {
     method: OpenAPIHttpMethod;
     path: string;
     operation: OpenAPIOperation;

package/dist/openApiRouting/routeConverter.core.js

@@ -1,3 +1,5 @@
+import { buildOperationParameters } from "./routeSchema.core.js";
+import { buildOperationRequestBody, buildOperationResponses, } from "./routeContent.core.js";
 import { OpenAPIRouteError } from "../openApiErrors/openApiError.types.js";
 import { PATH_TEMPLATE_PARAMETER } from "../openApiConstants/openApiConstants.core.js";
 /**
@@ -71,56 +73,49 @@ export function extractPathParameters(path) {
     }
     return names;
 }
-function toParameter(parameter) {
-    return {
-        name: parameter.name,
-        in: parameter.in,
-        ...(parameter.description ? { description: parameter.description } : {}),
-        // A path parameter is required by the specification, so declaring one
-        // that is not required is a document that cannot validate.
-        required: parameter.in === "path" ? true : (parameter.required ?? false),
-        ...(parameter.deprecated ? { deprecated: true } : {}),
-        ...(parameter.schema !== undefined ? { schema: parameter.schema } : {}),
-        ...(parameter.example !== undefined ? { example: parameter.example } : {}),
-    };
-}
 /**
  * Builds the `responses` object for an operation.
  *
- * Every documented response is carried through. Only when a route documents
- * none at all is a `200` synthesized, because `responses` is required.
+ * Every documented response is carried through. A route that documents none
+ * gets a `default` "Undocumented response" and a warning through
+ * `options.onWarning`; no `200` is invented.
  */
-export function buildResponses(metadata) {
-    const declared = metadata?.openapi?.responses;
-    if (declared && Object.keys(declared).length > 0) {
-        return Object.freeze({ ...declared });
-    }
-    return Object.freeze({ "200": { description: "OK" } });
+export function buildResponses(metadata, options) {
+    return buildOperationResponses(metadata?.openapi, "responses", options);
 }
 /**
  * Converts a route with metadata into an OpenAPI operation.
+ *
+ * Every path template slot is documented as a required path parameter even
+ * when the route declares none; schemas declared as `params`, `query`,
+ * `headers`, `cookies`, `body` or response `schema` are converted for
+ * `options.version`.
  */
-export function convertRouteToOpenAPI(method, path, metadata) {
+export function convertRouteToOpenAPI(method, path, metadata, options = {}) {
     if (!isOpenAPIMethod(method)) {
         throw new OpenAPIRouteError(`HTTP method "${method}" has no OpenAPI path item field. ` +
             `Supported: ${ZUDOLIB_TO_OPENAPI_METHODS.join(", ")}.`, { metadata: { method, path } });
     }
     const openApiPath = toOpenAPIPath(path);
     const meta = metadata?.openapi;
+    const context = `${method.toUpperCase()} ${path}`;
+    const parameters = buildOperationParameters(extractPathParameters(openApiPath), meta, context, options);
+    const requestBody = buildOperationRequestBody(meta, context, options);
     const operation = {
         ...(meta?.operationId ? { operationId: meta.operationId } : {}),
         ...(meta?.summary ? { summary: meta.summary } : {}),
         ...(meta?.description ? { description: meta.description } : {}),
         ...(meta?.tags?.length ? { tags: [...meta.tags] } : {}),
         ...(meta?.deprecated !== undefined ? { deprecated: meta.deprecated } : {}),
-        ...(meta?.parameters?.length
-            ? { parameters: meta.parameters.map(toParameter) }
-            : {}),
-        ...(meta?.requestBody ? { requestBody: meta.requestBody } : {}),
-        ...(meta?.security?.length ? { security: [...meta.security] } : {}),
+        ...(parameters.length > 0 ? { parameters } : {}),
+        ...(requestBody ? { requestBody } : {}),
+        // An empty list is meaningful: it marks the operation public, overriding
+        // document-level security. Dropping it documented a public route as
+        // requiring every global scheme.
+        ...(meta?.security !== undefined ? { security: [...meta.security] } : {}),
         ...(meta?.servers?.length ? { servers: [...meta.servers] } : {}),
         ...(meta?.externalDocs ? { externalDocs: meta.externalDocs } : {}),
-        responses: buildResponses(metadata),
+        responses: buildOperationResponses(meta, context, options),
     };
     return {
         method: method.toLowerCase(),

package/dist/openApiRouting/routeMetadata.type.d.ts

@@ -8,6 +8,8 @@
  * use.
  */
 import type { OpenAPIExternalDocumentation, OpenAPIRequestBody, OpenAPIResponse, OpenAPISecurityRequirement, OpenAPIServer } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIRouteBody, OpenAPIRouteResponse, OpenAPISchemaInput } from "../openApiSchema/schemaInput.type.js";
+export type { OpenAPIRouteBody, OpenAPIRouteResponse, OpenAPISchemaInput, RouteConversionOptions, } from "../openApiSchema/schemaInput.type.js";
 /** HTTP methods an OpenAPI path item can carry. */
 export type OpenAPIHttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
 /**
@@ -19,6 +21,7 @@ export interface RouteParameterMetadata {
     readonly description?: string;
     readonly required?: boolean;
     readonly deprecated?: boolean;
+    /** An {@link OpenAPISchemaInput}; a `@zudojs/schema` schema is converted. */
     readonly schema?: unknown;
     readonly example?: unknown;
 }
@@ -31,13 +34,44 @@ export interface RouteOpenAPIMetadata {
     readonly description?: string;
     readonly tags?: readonly string[];
     readonly deprecated?: boolean;
+    /**
+     * Explicit parameters. They take precedence over parameters derived from
+     * `params` / `query` / `headers` / `cookies` with the same name and
+     * location, which in turn take precedence over `inferredParameters`.
+     */
     readonly parameters?: readonly RouteParameterMetadata[];
+    /**
+     * Path parameters as one object schema; each property becomes an
+     * `in: "path"` parameter. Template slots it does not cover are still
+     * documented, as required strings.
+     */
+    readonly params?: OpenAPISchemaInput;
+    /** Query parameters as one object schema; one parameter per property. */
+    readonly query?: OpenAPISchemaInput;
+    /** Request headers as one object schema; one parameter per property. */
+    readonly headers?: OpenAPISchemaInput;
+    /** Cookies as one object schema; one parameter per property. */
+    readonly cookies?: OpenAPISchemaInput;
+    /**
+     * Parameters the route source inferred on its own (for example a regular
+     * expression constraint on a path segment). Lowest precedence: any
+     * declared parameter with the same name and location replaces one.
+     */
+    readonly inferredParameters?: readonly RouteParameterMetadata[];
+    /**
+     * The request body as a schema (`application/json`) or an
+     * {@link OpenAPIRouteBody}. Ignored when `requestBody` is set.
+     */
+    readonly body?: OpenAPISchemaInput | OpenAPIRouteBody;
+    /** A raw Request Body Object; takes precedence over `body`. */
     readonly requestBody?: OpenAPIRequestBody;
     /**
      * Responses keyed by status code, `default`, or a `2XX`-style range.
-     * Every entry reaches the document — this is not a 200-only field.
+     * Every entry reaches the document — this is not a 200-only field. An
+     * entry is a Response Object, or an {@link OpenAPIRouteResponse} when it
+     * carries a `schema`.
      */
-    readonly responses?: Readonly<Record<string, OpenAPIResponse>>;
+    readonly responses?: Readonly<Record<string, OpenAPIResponse | OpenAPIRouteResponse>>;
     readonly security?: readonly OpenAPISecurityRequirement[];
     readonly servers?: readonly OpenAPIServer[];
     readonly externalDocs?: OpenAPIExternalDocumentation;

package/dist/openApiRouting/routeScanner.core.d.ts

@@ -1,5 +1,5 @@
 import type { OpenAPIRoute } from "../openApiRegistry/openApiRegistry.type.js";
-import type { RouteInfo } from "./routeMetadata.type.js";
+import type { RouteConversionOptions, RouteInfo } from "./routeMetadata.type.js";
 /**
  * Collects routes and converts them into OpenAPI operations.
  *
@@ -20,8 +20,12 @@ export declare class OpenAPIRouteScannerImpl {
     removeRoute(method: string, path: string): boolean;
     /** Number of registered routes. */
     get size(): number;
-    /** Converts every registered route into an OpenAPI operation. */
-    scan(): readonly OpenAPIRoute[];
+    /**
+     * Converts every registered route into an OpenAPI operation. `options`
+     * sets the version declared schemas are converted for and receives their
+     * conversion warnings.
+     */
+    scan(options?: RouteConversionOptions): readonly OpenAPIRoute[];
     clear(): void;
 }
 //# sourceMappingURL=routeScanner.core.d.ts.map

package/dist/openApiRouting/routeScanner.core.js

@@ -1,5 +1,27 @@
-import { convertRouteToOpenAPI } from "./routeConverter.core.js";
+import { convertRouteToOpenAPI, toOpenAPIPath } from "./routeConverter.core.js";
 import { OpenAPIRouteError } from "../openApiErrors/openApiError.types.js";
+/**
+ * Identity of a route inside the generated document.
+ *
+ * Keyed on the OpenAPI path template rather than the source path, because
+ * that is what the document is keyed on: `/users/:id` and `/users/{id}` are
+ * one path item. Keying on the raw spelling let both register, and the
+ * second then replaced the first during generation — one operation vanished
+ * from the published spec with `validate()` reporting nothing.
+ *
+ * A path `toOpenAPIPath` cannot express keeps its raw spelling here so the
+ * conversion error still surfaces from `scan()`, where it always has.
+ */
+function routeKey(method, path) {
+    let template;
+    try {
+        template = toOpenAPIPath(path);
+    }
+    catch {
+        template = path;
+    }
+    return `${method.toLowerCase()}:${template}`;
+}
 /**
  * Collects routes and converts them into OpenAPI operations.
  *
@@ -12,35 +34,49 @@ export class OpenAPIRouteScannerImpl {
     routes = new Map();
     /** Registers a route. */
     addRoute(route) {
-        const key = `${route.method.toLowerCase()}:${route.path}`;
-        if (this.routes.has(key)) {
-            throw new OpenAPIRouteError(`Route ${route.method.toUpperCase()} ${route.path} is already registered.`, { metadata: { method: route.method, path: route.path } });
+        const key = routeKey(route.method, route.path);
+        const existing = this.routes.get(key);
+        if (existing !== undefined) {
+            throw new OpenAPIRouteError(`Route ${route.method.toUpperCase()} ${route.path} is already registered` +
+                (existing.path === route.path
+                    ? "."
+                    : ` as ${existing.method.toUpperCase()} ${existing.path}; both describe the same OpenAPI path.`), {
+                metadata: {
+                    method: route.method,
+                    path: route.path,
+                    existingPath: existing.path,
+                },
+            });
         }
         this.routes.set(key, route);
     }
     /** Registers a route, replacing any existing one for the same method+path. */
     setRoute(route) {
-        this.routes.set(`${route.method.toLowerCase()}:${route.path}`, route);
+        this.routes.set(routeKey(route.method, route.path), route);
     }
     /** True when a route is registered for this method and path. */
     hasRoute(method, path) {
-        return this.routes.has(`${method.toLowerCase()}:${path}`);
+        return this.routes.has(routeKey(method, path));
     }
     /** Removes a route. Returns whether one was removed. */
     removeRoute(method, path) {
-        return this.routes.delete(`${method.toLowerCase()}:${path}`);
+        return this.routes.delete(routeKey(method, path));
     }
     /** Number of registered routes. */
     get size() {
         return this.routes.size;
     }
-    /** Converts every registered route into an OpenAPI operation. */
-    scan() {
+    /**
+     * Converts every registered route into an OpenAPI operation. `options`
+     * sets the version declared schemas are converted for and receives their
+     * conversion warnings.
+     */
+    scan(options) {
         const result = [];
         for (const route of this.routes.values()) {
             if (route.metadata?.openapi?.hidden === true)
                 continue;
-            const converted = convertRouteToOpenAPI(route.method, route.path, route.metadata);
+            const converted = convertRouteToOpenAPI(route.method, route.path, route.metadata, options);
             result.push({
                 method: converted.method,
                 path: converted.path,

package/dist/openApiRouting/routeSchema.core.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Schema-aware parameter derivation for route conversion: path parameters,
+ * query, headers and cookies declared as one object schema each become one
+ * parameter per property.
+ */
+import type { OpenAPIParameter } from "../openApiTypes/openApiTypes.core.js";
+import type { RouteConversionOptions, RouteOpenAPIMetadata } from "./routeMetadata.type.js";
+/**
+ * Builds an operation's parameter list.
+ *
+ * `slots` are the path template's parameter names. Layers, lowest precedence
+ * first: a required string per slot, `inferredParameters`, the `params` /
+ * `query` / `headers` / `cookies` schemas, then explicit `parameters`; a
+ * later layer replaces a parameter with the same name and location. A path
+ * parameter no slot names is dropped with a warning: emitting it would make
+ * a document that cannot validate.
+ */
+export declare function buildOperationParameters(slots: readonly string[], meta: RouteOpenAPIMetadata | undefined, context: string, options?: RouteConversionOptions): readonly OpenAPIParameter[];
+//# sourceMappingURL=routeSchema.core.d.ts.map

package/dist/openApiRouting/routeSchema.core.js

@@ -0,0 +1,93 @@
+/**
+ * Schema-aware parameter derivation for route conversion: path parameters,
+ * query, headers and cookies declared as one object schema each become one
+ * parameter per property.
+ */
+import { resolveSchemaInput } from "../openApiSchema/schemaInput.core.js";
+function isObjectSchema(schema) {
+    const type = schema.type;
+    if (type === "object")
+        return true;
+    if (Array.isArray(type))
+        return type.includes("object");
+    return type === undefined && schema.properties !== undefined;
+}
+/** One parameter per property of an object schema. */
+function parametersFromSchema(input, location, context, options) {
+    const schema = resolveSchemaInput(input, context, options);
+    if (!isObjectSchema(schema) || schema.properties === undefined) {
+        options.onWarning?.(`${context}: ${location} parameters must be declared as an object schema; ignored.`);
+        return [];
+    }
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties).map(([name, property]) => ({
+        name,
+        in: location,
+        required: location === "path" ? true : required.has(name),
+        ...(property.description ? { description: property.description } : {}),
+        ...(property.deprecated ? { deprecated: true } : {}),
+        schema: property,
+    }));
+}
+function toParameter(parameter, context, options) {
+    return {
+        name: parameter.name,
+        in: parameter.in,
+        ...(parameter.description ? { description: parameter.description } : {}),
+        // A path parameter is required by the specification, so declaring one
+        // that is not required is a document that cannot validate.
+        required: parameter.in === "path" ? true : (parameter.required ?? false),
+        ...(parameter.deprecated ? { deprecated: true } : {}),
+        ...(parameter.schema === undefined ? {} : {
+            schema: resolveSchemaInput(parameter.schema, `${context} "${parameter.name}"`, options),
+        }),
+        ...(parameter.example !== undefined ? { example: parameter.example } : {}),
+    };
+}
+const SCHEMA_LOCATIONS = [
+    ["params", "path"],
+    ["query", "query"],
+    ["headers", "header"],
+    ["cookies", "cookie"],
+];
+/**
+ * Builds an operation's parameter list.
+ *
+ * `slots` are the path template's parameter names. Layers, lowest precedence
+ * first: a required string per slot, `inferredParameters`, the `params` /
+ * `query` / `headers` / `cookies` schemas, then explicit `parameters`; a
+ * later layer replaces a parameter with the same name and location. A path
+ * parameter no slot names is dropped with a warning: emitting it would make
+ * a document that cannot validate.
+ */
+export function buildOperationParameters(slots, meta, context, options = {}) {
+    const merged = new Map();
+    const put = (parameter) => void merged.set(`${parameter.in}:${parameter.name}`, parameter);
+    for (const name of slots) {
+        put({ name, in: "path", required: true, schema: { type: "string" } });
+    }
+    for (const parameter of meta?.inferredParameters ?? []) {
+        put(toParameter(parameter, context, options));
+    }
+    for (const [key, location] of SCHEMA_LOCATIONS) {
+        const input = meta?.[key];
+        if (input === undefined)
+            continue;
+        for (const parameter of parametersFromSchema(input, location, context, options)) {
+            put(parameter);
+        }
+    }
+    for (const parameter of meta?.parameters ?? []) {
+        put(toParameter(parameter, context, options));
+    }
+    const result = [];
+    for (const parameter of merged.values()) {
+        if (parameter.in === "path" && !slots.includes(parameter.name)) {
+            options.onWarning?.(`${context}: path parameter "${parameter.name}" is not in the path template; ignored.`);
+            continue;
+        }
+        result.push(parameter);
+    }
+    return result;
+}
+//# sourceMappingURL=routeSchema.core.js.map

package/dist/openApiSchema/index.d.ts

@@ -8,4 +8,5 @@ export { convertSchema, createSchemaConverter, isVersion31, } from "./schemaConv
 export type { SchemaRegistry, SchemaRegistryOptions, } from "./schemaRegistry.core.js";
 export { SchemaRegistryImpl } from "./schemaRegistry.core.js";
 export { createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, type ComponentSection, } from "./references.core.js";
+export { isSchemaDefinition, resolveSchemaInput, type SchemaInputOptions, } from "./schemaInput.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiSchema/index.js

@@ -6,4 +6,5 @@
 export { convertSchema, createSchemaConverter, isVersion31, } from "./schemaConverter.core.js";
 export { SchemaRegistryImpl } from "./schemaRegistry.core.js";
 export { createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, } from "./references.core.js";
+export { isSchemaDefinition, resolveSchemaInput, } from "./schemaInput.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiSchema/schemaConverter.core.d.ts

@@ -11,6 +11,8 @@ import type { OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
  *
  * Field names as of `@zudojs/schema@0.1.0`:
  *   object   `_config.shape`, `_config.requiredKeys` (a Set), `_config.unknownKeys`
+ *            (`"strip" | "strict" | "passthrough"`; absent means the parser's
+ *            own `?? "strip"` default, so it is read with that same default)
  *   array    `_config.itemSchema`, `_config.min`, `_config.max`, `_config.length`
  *            (no `max` means the parser's implicit ceiling, which is emitted)
  *   string   `_config.min|max|length|pattern|format`

package/dist/openApiSchema/schemaConverter.core.js

@@ -309,14 +309,19 @@ function convertSchemaNode(schema, state) {
                 if (forced || !acceptsMissingKey(value))
                     required.push(key);
             }
-            const unknownKeys = c["unknownKeys"];
+            // `ObjectSchema` applies `?? "strip"` internally, so an absent
+            // `unknownKeys` is the same contract as an explicit `.strip()` and
+            // must document the same. Only `strict` emits
+            // `additionalProperties: false`: that is OpenAPI for "reject the
+            // payload", while strip accepts it and discards the extra key, so
+            // emitting it for strip made a generated client refuse what the
+            // service accepts.
+            const unknownKeys = c["unknownKeys"] ?? "strip";
             return {
                 type: "object",
                 ...(Object.keys(properties).length > 0 ? { properties } : {}),
                 ...(required.length > 0 ? { required } : {}),
-                ...(unknownKeys === "strip" || unknownKeys === "strict"
-                    ? { additionalProperties: false }
-                    : {}),
+                ...(unknownKeys === "strict" ? { additionalProperties: false } : {}),
             };
         }
         case "record": {

package/dist/openApiSchema/schemaInput.core.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolution of schemas declared on routes and operations.
+ *
+ * A declared schema is either a `@zudojs/schema` schema, converted here for
+ * the target version, or an OpenAPI Schema / Reference Object used as-is.
+ */
+import type { OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
+/** Options for {@link resolveSchemaInput}. */
+export interface SchemaInputOptions {
+    /** Specification version to convert for. Default: 3.1.0. */
+    readonly version?: string;
+    /** Receives everything a conversion could not express exactly. */
+    readonly onWarning?: (message: string) => void;
+}
+/** True when `value` is a `@zudojs/schema` schema (it carries a string `_type`). */
+export declare function isSchemaDefinition(value: unknown): value is {
+    readonly _type: string;
+};
+/**
+ * Resolves a declared schema to an OpenAPI schema.
+ *
+ * A `@zudojs/schema` schema is converted and each conversion warning is
+ * reported prefixed with `context`; any other object is taken to be an
+ * OpenAPI Schema or Reference Object already. A non-object is reported and
+ * becomes `{}`.
+ */
+export declare function resolveSchemaInput(input: unknown, context: string, options?: SchemaInputOptions): OpenAPISchema;
+//# sourceMappingURL=schemaInput.core.d.ts.map

package/dist/openApiSchema/schemaInput.core.js

@@ -0,0 +1,36 @@
+/**
+ * Resolution of schemas declared on routes and operations.
+ *
+ * A declared schema is either a `@zudojs/schema` schema, converted here for
+ * the target version, or an OpenAPI Schema / Reference Object used as-is.
+ */
+import { convertSchema } from "./schemaConverter.core.js";
+/** True when `value` is a `@zudojs/schema` schema (it carries a string `_type`). */
+export function isSchemaDefinition(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value._type === "string");
+}
+/**
+ * Resolves a declared schema to an OpenAPI schema.
+ *
+ * A `@zudojs/schema` schema is converted and each conversion warning is
+ * reported prefixed with `context`; any other object is taken to be an
+ * OpenAPI Schema or Reference Object already. A non-object is reported and
+ * becomes `{}`.
+ */
+export function resolveSchemaInput(input, context, options = {}) {
+    if (isSchemaDefinition(input)) {
+        const result = convertSchema(input, { version: options.version });
+        for (const warning of result.warnings) {
+            options.onWarning?.(`${context}: ${warning}`);
+        }
+        return result.schema;
+    }
+    if (typeof input === "object" && input !== null) {
+        return input;
+    }
+    options.onWarning?.(`${context}: expected a schema, got ${typeof input}; emitted {}.`);
+    return {};
+}
+//# sourceMappingURL=schemaInput.core.js.map