@zudojs/openapi 1.4.0 → 1.5.0

package/README.md

@@ -51,8 +51,12 @@ const yaml = manager.toYAML();
 ```
 
 Every documented response reaches the document — `4xx`, `5xx` and `default`
-included. `:id` becomes `{id}`, and a path parameter is marked required
-because the specification requires it.
+included. `:id` becomes `{id}`, every template slot is documented as a
+required path parameter (declared or not), and `params` / `query` /
+`headers` / `body` / response `schema` fields accept `@zudojs/schema` schemas
+— see [Generating from a route table](#generating-from-a-route-table). To
+generate from an `@zudojs/http` router instead of adding routes by hand, use
+that package's `generateOpenAPIDocument(router)` or `mountOpenAPI(router)`.
 
 Generation is idempotent: call `generate()` as often as you like.
 
@@ -134,6 +138,83 @@ scheme is read after stripping the control characters browsers ignore, so
 `customCss` containing `</style>` throws — that sequence ends the style block
 and lets the rest be parsed as HTML.
 
+## Generating from a route table
+
+`createOpenAPIDocumentFromRoutes(routes, options)` builds a document from a
+list of structural `OpenAPIRouteDescriptor`s, so any route source can be
+documented from what it actually registers. `@zudojs/http`'s
+`generateOpenAPIDocument(router)` and `mountOpenAPI(router)` feed it the
+router's routes; other sources (such as `@zudojs/api` operations) build the
+same descriptors.
+
+```typescript
+import { createOpenAPIDocumentFromRoutes } from "@zudojs/openapi";
+import { objectSchema, stringSchema } from "@zudojs/schema";
+
+const user = objectSchema({ id: stringSchema().uuid(), name: stringSchema() });
+
+const document = createOpenAPIDocumentFromRoutes(
+  [
+    { method: "GET", path: "/users/:id", summary: "Get a user", tags: ["users"],
+      responses: { "200": { schema: user }, "404": { description: "No such user" } } },
+    { method: "POST", path: "/users", operationId: "users.create",
+      body: objectSchema({ name: stringSchema() }),
+      responses: { "201": { schema: user } } },
+  ],
+  {
+    info: { title: "Users API", version: "1.0.0" },
+    securitySchemes: { bearer: { type: "http", scheme: "bearer" } },
+    security: [{ bearer: [] }],
+    schemas: { User: user },   // components; converted when they are @zudojs/schema schemas
+    validate: true,
+  },
+);
+```
+
+An `OpenAPIRouteDescriptor` is `RouteOpenAPIMetadata` plus `method` and
+`path`, flattened:
+
+| Field | Meaning |
+| --- | --- |
+| `method` | Any case; must be `get put post delete options head patch trace` |
+| `path` | `/users/:id` or `/users/{id}`; optional/regex/wildcard segments are resolved by the source |
+| `summary`, `description`, `operationId`, `tags`, `deprecated`, `servers`, `externalDocs` | Copied to the operation |
+| `security` | Operation security; `[]` marks it public (overrides document security) |
+| `params`, `query`, `headers`, `cookies` | One object schema each; every property becomes a parameter (`required` from the schema; path parameters always required) |
+| `body` | A schema (sent as `application/json`, required) or `{ schema, contentType?, required?, description?, example? }`; a raw `requestBody` wins |
+| `responses` | Per status / `NXX` / `default`: a Response Object, or `{ schema, description?, contentType?, headers?, example? }` (description defaults to the reason phrase, e.g. "Not Found") |
+| `parameters` | Explicit parameters, highest precedence |
+| `inferredParameters` | Parameters the source derived itself (e.g. a regex constraint), lowest precedence |
+| `hidden` | `true` leaves the operation out |
+
+Every path template slot is documented as a required string parameter even
+when nothing declares it, and a declared path parameter the template does
+not contain is dropped with a warning rather than producing an invalid
+document. The same metadata fields work in `manager.addRoute({ method, path,
+metadata: { openapi } })`. Conversion warnings reach `onRouteWarning`
+(one message at a time), `onSchemaWarning` under the name `"routes"`, and
+`manager.routeWarnings()`, each prefixed with the route (`DELETE /users/:id: ...`).
+
+No response status is invented. A route that documents no responses (or
+`responses: {}`) gets a spec-valid `default` response described as
+`"Undocumented response"` (`UNDOCUMENTED_RESPONSE_DESCRIPTION`) and a route
+warning, so the omission shows up instead of a `204` DELETE being published
+as `200`:
+
+```typescript
+const document = createOpenAPIDocumentFromRoutes(
+  [{ method: "DELETE", path: "/users/:id" }],
+  { info, onRouteWarning: (message) => logger.warn(message) },
+);
+// paths["/users/{id}"].delete.responses → { default: { description: "Undocumented response" } }
+// warned: "DELETE /users/:id: no responses are documented; ..."
+```
+
+`createOpenAPIManagerFromRoutes(routes, options)` returns the manager instead
+(for `toResponse` / `toUIResponse`); `manager.setRoutes(routes)` replaces its
+whole route set, rejecting duplicates before anything changes, and
+`routeDescriptorToRouteInfo` converts a descriptor to `addRoute`'s shape.
+
 ## Branding
 
 ReDoc, Scalar and several other viewers read a logo from the non-standard

package/dist/index.d.ts

@@ -4,7 +4,9 @@
  * API contract and documentation engine for the Zudojs framework.
  *
  * Generates OpenAPI specifications from application routes, schemas,
- * and metadata. Supports OpenAPI 3.0 and 3.1.
+ * and metadata. Supports OpenAPI 3.0 and 3.1. A route table from any source
+ * becomes a document through `createOpenAPIDocumentFromRoutes`;
+ * `@zudojs/http` uses it to document a router's registered routes.
  *
  * @example
  * ```ts
@@ -42,11 +44,13 @@ export { OpenAPIDocumentBuilder, createOpenAPIDocumentBuilder, type OpenAPIDocum
 export { OpenAPIRegistryImpl } from "./openApiRegistry/index.js";
 export type { OpenAPIRegistry, OpenAPIRoute, OpenAPIComponentRegistration, } from "./openApiRegistry/index.js";
 export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, formatIssuePath, type OpenAPIErrorOptions, type OpenAPIValidationIssue, } from "./openApiErrors/index.js";
-export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants/index.js";
-export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, } from "./openApiRouting/index.js";
-export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, OpenAPIHttpMethod, } from "./openApiRouting/index.js";
-export { convertSchema, createSchemaConverter, isVersion31, SchemaRegistryImpl, createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, } from "./openApiSchema/index.js";
-export type { SchemaConverter, SchemaConversionResult, SchemaConversionOptions, SchemaRegistry, SchemaRegistryOptions, ComponentSection, } from "./openApiSchema/index.js";
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, UNDOCUMENTED_RESPONSE_DESCRIPTION, } from "./openApiConstants/index.js";
+export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, buildOperationParameters, buildOperationRequestBody, buildOperationResponses, describeResponseKey, } from "./openApiRouting/index.js";
+export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, OpenAPIHttpMethod, OpenAPISchemaInput, OpenAPIRouteBody, OpenAPIRouteResponse, RouteConversionOptions, } from "./openApiRouting/index.js";
+export { createOpenAPIDocumentFromRoutes, createOpenAPIManagerFromRoutes, routeDescriptorToRouteInfo, } from "./openApiFromRoutes/index.js";
+export type { OpenAPIRouteDescriptor, OpenAPIDocumentFromRoutesOptions, } from "./openApiFromRoutes/index.js";
+export { convertSchema, createSchemaConverter, isVersion31, SchemaRegistryImpl, createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, isSchemaDefinition, resolveSchemaInput, } from "./openApiSchema/index.js";
+export type { SchemaInputOptions, SchemaConverter, SchemaConversionResult, SchemaConversionOptions, SchemaRegistry, SchemaRegistryOptions, ComponentSection, } from "./openApiSchema/index.js";
 export { OpenAPIValidatorImpl, createOpenAPIValidator, } from "./openApiValidation/index.js";
 export type { OpenAPIValidator, OpenAPIValidationResult, } from "./openApiValidation/index.js";
 export { toOpenAPIJSON, toOpenAPIYAML, } from "./openApiSerialization/openApiSerializer.core.js";

package/dist/index.js

@@ -4,7 +4,9 @@
  * API contract and documentation engine for the Zudojs framework.
  *
  * Generates OpenAPI specifications from application routes, schemas,
- * and metadata. Supports OpenAPI 3.0 and 3.1.
+ * and metadata. Supports OpenAPI 3.0 and 3.1. A route table from any source
+ * becomes a document through `createOpenAPIDocumentFromRoutes`;
+ * `@zudojs/http` uses it to document a router's registered routes.
  *
  * @example
  * ```ts
@@ -46,11 +48,13 @@ export { OpenAPIRegistryImpl } from "./openApiRegistry/index.js";
 /* ─── Errors ────────────────────────────────────────────────────────────── */
 export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, formatIssuePath, } from "./openApiErrors/index.js";
 /* ─── Constants ─────────────────────────────────────────────────────────── */
-export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants/index.js";
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, UNDOCUMENTED_RESPONSE_DESCRIPTION, } from "./openApiConstants/index.js";
 /* ─── Routing ───────────────────────────────────────────────────────────── */
-export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, } from "./openApiRouting/index.js";
+export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, buildOperationParameters, buildOperationRequestBody, buildOperationResponses, describeResponseKey, } from "./openApiRouting/index.js";
+/* ─── Generation from a route table ────────────────────────────────────── */
+export { createOpenAPIDocumentFromRoutes, createOpenAPIManagerFromRoutes, routeDescriptorToRouteInfo, } from "./openApiFromRoutes/index.js";
 /* ─── Schema conversion ─────────────────────────────────────────────────── */
-export { convertSchema, createSchemaConverter, isVersion31, SchemaRegistryImpl, createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, } from "./openApiSchema/index.js";
+export { convertSchema, createSchemaConverter, isVersion31, SchemaRegistryImpl, createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, isSchemaDefinition, resolveSchemaInput, } from "./openApiSchema/index.js";
 /* ─── Validation ────────────────────────────────────────────────────────── */
 export { OpenAPIValidatorImpl, createOpenAPIValidator, } from "./openApiValidation/index.js";
 /* ─── Serialization ─────────────────────────────────────────────────────── */

package/dist/openApiConstants/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * @zudojs/openapi/openApiConstants
  */
-export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants.core.js";
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, UNDOCUMENTED_RESPONSE_DESCRIPTION, } from "./openApiConstants.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiConstants/index.js

@@ -1,5 +1,5 @@
 /**
  * @zudojs/openapi/openApiConstants
  */
-export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants.core.js";
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, UNDOCUMENTED_RESPONSE_DESCRIPTION, } from "./openApiConstants.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiConstants/openApiConstants.core.d.ts

@@ -39,6 +39,11 @@ export declare const STATUS_CODE_CATEGORIES: {
 export declare const RESPONSE_KEY_PATTERN: RegExp;
 /** OpenAPI path template parameter, e.g. `{orderId}`. */
 export declare const PATH_TEMPLATE_PARAMETER: RegExp;
+/**
+ * Description of the `default` response emitted for an operation that
+ * documents no responses. No status code is invented for it.
+ */
+export declare const UNDOCUMENTED_RESPONSE_DESCRIPTION = "Undocumented response";
 /**
  * Default server URL.
  */

package/dist/openApiConstants/openApiConstants.core.js

@@ -46,6 +46,11 @@ export const STATUS_CODE_CATEGORIES = {
 export const RESPONSE_KEY_PATTERN = /^(default|[1-5](XX|\d{2}))$/;
 /** OpenAPI path template parameter, e.g. `{orderId}`. */
 export const PATH_TEMPLATE_PARAMETER = /\{([^{}]+)\}/g;
+/**
+ * Description of the `default` response emitted for an operation that
+ * documents no responses. No status code is invented for it.
+ */
+export const UNDOCUMENTED_RESPONSE_DESCRIPTION = "Undocumented response";
 /**
  * Default server URL.
  */

package/dist/openApiFromRoutes/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @zudojs/openapi/openApiFromRoutes
+ *
+ * Generates a document from a route table described by transport-neutral
+ * {@link OpenAPIRouteDescriptor}s, so any route source — an `@zudojs/http`
+ * router, an `@zudojs/api` registry, a hand-written list — can be documented
+ * from what it actually registers.
+ */
+export type { OpenAPIRouteDescriptor, OpenAPIDocumentFromRoutesOptions, } from "./openApiFromRoutes.type.js";
+export { createOpenAPIDocumentFromRoutes, createOpenAPIManagerFromRoutes, routeDescriptorToRouteInfo, } from "./openApiFromRoutes.document.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/openApiFromRoutes/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/openapi/openApiFromRoutes
+ *
+ * Generates a document from a route table described by transport-neutral
+ * {@link OpenAPIRouteDescriptor}s, so any route source — an `@zudojs/http`
+ * router, an `@zudojs/api` registry, a hand-written list — can be documented
+ * from what it actually registers.
+ */
+export { createOpenAPIDocumentFromRoutes, createOpenAPIManagerFromRoutes, routeDescriptorToRouteInfo, } from "./openApiFromRoutes.document.js";
+//# sourceMappingURL=index.js.map

package/dist/openApiFromRoutes/openApiFromRoutes.document.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Document generation from a route table.
+ */
+import type { OpenAPIDocument } from "../openApiTypes/openApiTypes.core.js";
+import type { RouteInfo } from "../openApiRouting/routeMetadata.type.js";
+import { OpenAPIManager } from "../openApiHttp/openApiHttpAdapter.core.js";
+import type { OpenAPIDocumentFromRoutesOptions, OpenAPIRouteDescriptor } from "./openApiFromRoutes.type.js";
+/**
+ * Splits a descriptor into the manager's `{ method, path, metadata }` shape.
+ *
+ * @throws {OpenAPIRouteError} When the method has no OpenAPI path item field.
+ */
+export declare function routeDescriptorToRouteInfo(descriptor: OpenAPIRouteDescriptor): RouteInfo;
+/**
+ * Creates an {@link OpenAPIManager} holding `routes`, ready to generate,
+ * serialize and serve (`toResponse`, `toUIResponse`). Refresh it later with
+ * `manager.setRoutes(descriptors.map(routeDescriptorToRouteInfo))`.
+ *
+ * @throws {OpenAPIRouteError} On an unsupported method or a duplicate route.
+ */
+export declare function createOpenAPIManagerFromRoutes(routes: readonly OpenAPIRouteDescriptor[], options: OpenAPIDocumentFromRoutesOptions): OpenAPIManager;
+/**
+ * Generates an OpenAPI document from a list of route descriptors.
+ *
+ * This is the transport-neutral entry point: `@zudojs/http` feeds it the
+ * routes a router actually has registered, and any other source can feed it
+ * the same structural {@link OpenAPIRouteDescriptor}s.
+ *
+ * ```ts
+ * const document = createOpenAPIDocumentFromRoutes(
+ *   [{ method: "GET", path: "/users/:id", summary: "Get a user",
+ *      responses: { "200": { schema: userSchema } } }],
+ *   { info: { title: "Users", version: "1.0.0" }, validate: true },
+ * );
+ * ```
+ *
+ * @throws {OpenAPIRouteError} On an unsupported method, an inexpressible
+ *   path or a duplicate route.
+ * @throws {OpenAPIValidationError} When `validate` is set and the document
+ *   is invalid.
+ */
+export declare function createOpenAPIDocumentFromRoutes(routes: readonly OpenAPIRouteDescriptor[], options: OpenAPIDocumentFromRoutesOptions): OpenAPIDocument;
+//# sourceMappingURL=openApiFromRoutes.document.d.ts.map

package/dist/openApiFromRoutes/openApiFromRoutes.document.js

@@ -0,0 +1,64 @@
+/**
+ * Document generation from a route table.
+ */
+import { isOpenAPIMethod } from "../openApiRouting/routeConverter.core.js";
+import { isSchemaDefinition } from "../openApiSchema/schemaInput.core.js";
+import { OpenAPIManager } from "../openApiHttp/openApiHttpAdapter.core.js";
+import { OpenAPIRouteError } from "../openApiErrors/openApiError.types.js";
+/**
+ * Splits a descriptor into the manager's `{ method, path, metadata }` shape.
+ *
+ * @throws {OpenAPIRouteError} When the method has no OpenAPI path item field.
+ */
+export function routeDescriptorToRouteInfo(descriptor) {
+    const { method, path, ...openapi } = descriptor;
+    if (typeof method !== "string" || !isOpenAPIMethod(method)) {
+        throw new OpenAPIRouteError(`HTTP method "${String(method)}" of route ${String(path)} has no OpenAPI path item field.`, { metadata: { method, path } });
+    }
+    return { method: method.toLowerCase(), path, metadata: { openapi } };
+}
+/**
+ * Creates an {@link OpenAPIManager} holding `routes`, ready to generate,
+ * serialize and serve (`toResponse`, `toUIResponse`). Refresh it later with
+ * `manager.setRoutes(descriptors.map(routeDescriptorToRouteInfo))`.
+ *
+ * @throws {OpenAPIRouteError} On an unsupported method or a duplicate route.
+ */
+export function createOpenAPIManagerFromRoutes(routes, options) {
+    const { validate: _validate, securitySchemes, schemas, ...managerOptions } = options;
+    const manager = new OpenAPIManager({ ...managerOptions, cacheTtlMs: 0 });
+    for (const [name, scheme] of Object.entries(securitySchemes ?? {})) {
+        manager.addSecurityScheme(name, scheme);
+    }
+    for (const [name, schema] of Object.entries(schemas ?? {})) {
+        if (isSchemaDefinition(schema))
+            manager.addSchema(name, schema);
+        else
+            manager.addRawSchema(name, schema);
+    }
+    return manager.setRoutes(routes.map(routeDescriptorToRouteInfo));
+}
+/**
+ * Generates an OpenAPI document from a list of route descriptors.
+ *
+ * This is the transport-neutral entry point: `@zudojs/http` feeds it the
+ * routes a router actually has registered, and any other source can feed it
+ * the same structural {@link OpenAPIRouteDescriptor}s.
+ *
+ * ```ts
+ * const document = createOpenAPIDocumentFromRoutes(
+ *   [{ method: "GET", path: "/users/:id", summary: "Get a user",
+ *      responses: { "200": { schema: userSchema } } }],
+ *   { info: { title: "Users", version: "1.0.0" }, validate: true },
+ * );
+ * ```
+ *
+ * @throws {OpenAPIRouteError} On an unsupported method, an inexpressible
+ *   path or a duplicate route.
+ * @throws {OpenAPIValidationError} When `validate` is set and the document
+ *   is invalid.
+ */
+export function createOpenAPIDocumentFromRoutes(routes, options) {
+    return createOpenAPIManagerFromRoutes(routes, options).generate(options.validate ?? false);
+}
+//# sourceMappingURL=openApiFromRoutes.document.js.map

package/dist/openApiFromRoutes/openApiFromRoutes.type.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Transport-neutral input for generating a document from a route table.
+ */
+import type { OpenAPIInfo, OpenAPISecurityScheme } from "../openApiTypes/openApiTypes.core.js";
+import type { RouteOpenAPIMetadata } from "../openApiRouting/routeMetadata.type.js";
+import type { OpenAPIManagerOptions } from "../openApiHttp/openApiHttpAdapter.core.js";
+/**
+ * One operation, described structurally so that any route source can feed
+ * {@link createOpenAPIDocumentFromRoutes}: an `@zudojs/http` router, an
+ * `@zudojs/api` operation registry, or a hand-written list.
+ *
+ * It is {@link RouteOpenAPIMetadata} plus the operation's method and path,
+ * flattened into one object:
+ *
+ * - `method` — any case (`"GET"`, `"post"`); it must be one an OpenAPI path
+ *   item can carry (`get put post delete options head patch trace`).
+ * - `path` — `/users/:id` or `/users/{id}`. Optional segments, typed or
+ *   regex-constrained `:name(...)` segments and wildcards have no OpenAPI
+ *   spelling; the source resolves them (see `inferredParameters`) before
+ *   handing the path over.
+ * - `summary`, `description`, `operationId`, `tags`, `deprecated`,
+ *   `security` (`[]` marks a public operation), `servers`, `externalDocs`.
+ * - `params`, `query`, `headers`, `cookies` — one object schema each; every
+ *   property becomes a parameter. A `@zudojs/schema` schema is converted, any
+ *   other object is used as an OpenAPI schema.
+ * - `body` — a schema, or `{ schema, contentType?, required?, description? }`.
+ * - `responses` — keyed by status, `NXX` range or `default`; each entry is a
+ *   Response Object or `{ schema, description?, contentType?, headers? }`.
+ * - `parameters` — explicit parameters, highest precedence.
+ * - `inferredParameters` — parameters the source derived itself, lowest
+ *   precedence.
+ * - `hidden: true` — leave the operation out of the document.
+ *
+ * Every path template slot is documented even when nothing declares it.
+ */
+export interface OpenAPIRouteDescriptor extends RouteOpenAPIMetadata {
+    /** HTTP method, any case. */
+    readonly method: string;
+    /** Route path, `/users/:id` or `/users/{id}`. */
+    readonly path: string;
+}
+/** Options for {@link createOpenAPIDocumentFromRoutes}. */
+export interface OpenAPIDocumentFromRoutesOptions extends Omit<OpenAPIManagerOptions, "info" | "cacheTtlMs" | "now"> {
+    /** Document metadata (title and version are required by the spec). */
+    readonly info: OpenAPIInfo;
+    /** Validate the result and throw `OpenAPIValidationError` if invalid. */
+    readonly validate?: boolean;
+    /** Registered under `components.securitySchemes`. */
+    readonly securitySchemes?: Readonly<Record<string, OpenAPISecurityScheme>>;
+    /**
+     * Component schemas, registered under `components.schemas`. A
+     * `@zudojs/schema` schema is converted; any other object is used as-is.
+     */
+    readonly schemas?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=openApiFromRoutes.type.d.ts.map

package/dist/openApiFromRoutes/openApiFromRoutes.type.js

@@ -0,0 +1,5 @@
+/**
+ * Transport-neutral input for generating a document from a route table.
+ */
+export {};
+//# sourceMappingURL=openApiFromRoutes.type.js.map

package/dist/openApiHttp/openApiHttpAdapter.core.d.ts

@@ -17,8 +17,20 @@ export interface OpenAPIManagerOptions {
      * invalidates the cache regardless.
      */
     readonly cacheTtlMs?: number;
-    /** Reports what a schema conversion could not express. */
+    /**
+     * Reports what a schema conversion could not express: component schemas
+     * under their component name, route-declared schemas and parameters under
+     * `"routes"` once per generation.
+     */
     readonly onSchemaWarning?: (name: string, warnings: readonly string[]) => void;
+    /**
+     * Receives each route warning of a generation as it is produced, each
+     * prefixed with the route (`DELETE /users/:id: ...`): route-declared
+     * schemas or parameters that could not be expressed, and operations that
+     * document no responses. The same messages are returned by
+     * {@link OpenAPIManager.routeWarnings}.
+     */
+    readonly onRouteWarning?: (message: string) => void;
     /** Supplies the clock, for tests. */
     readonly now?: () => number;
     /**
@@ -59,6 +71,9 @@ export declare class OpenAPIManager {
     private readonly logo;
     /** True when `branding` was a caller-supplied logo rather than the default. */
     private readonly customLogo;
+    private readonly onSchemaWarning;
+    private readonly onRouteWarning;
+    private lastRouteWarnings;
     private cachedDocument?;
     private cachedAt;
     /** Whether the cached document was produced by a validating generate. */
@@ -76,6 +91,12 @@ export declare class OpenAPIManager {
     addRoute(route: RouteInfo): this;
     /** Registers a route, replacing any existing one for the same method+path. */
     setRoute(route: RouteInfo): this;
+    /**
+     * Replaces every registered route with `routes`, for keeping the document
+     * in step with a live route table. Duplicates are rejected before anything
+     * is replaced, so a failed call leaves the previous routes in place.
+     */
+    setRoutes(routes: readonly RouteInfo[]): this;
     /** Removes a route. Returns whether one was removed. */
     removeRoute(method: OpenAPIHttpMethod, path: string): boolean;
     /**
@@ -89,6 +110,12 @@ export declare class OpenAPIManager {
     addRawSchema(name: string, schema: OpenAPISchema): this;
     /** Conversion warnings, keyed by component name. */
     schemaWarnings(): ReadonlyMap<string, readonly string[]>;
+    /**
+     * The route warnings of the last generation, each prefixed with the route
+     * (`GET /users/:id: ...`): what could not be expressed for route-declared
+     * schemas and parameters, and operations that document no responses.
+     */
+    routeWarnings(): readonly string[];
     /**
      * Builds the document from the registered routes and components.
      *

package/dist/openApiHttp/openApiHttpAdapter.core.js

@@ -24,6 +24,9 @@ export class OpenAPIManager {
     logo;
     /** True when `branding` was a caller-supplied logo rather than the default. */
     customLogo;
+    onSchemaWarning;
+    onRouteWarning;
+    lastRouteWarnings = [];
     cachedDocument;
     cachedAt = 0;
     /** Whether the cached document was produced by a validating generate. */
@@ -39,6 +42,8 @@ export class OpenAPIManager {
             version: options.version ?? DEFAULT_OPENAPI_VERSION,
             onWarning: options.onSchemaWarning,
         });
+        this.onSchemaWarning = options.onSchemaWarning;
+        this.onRouteWarning = options.onRouteWarning;
         this.cacheTtlMs = options.cacheTtlMs ?? DOCUMENT_CACHE_TTL_MS;
         this.now = options.now ?? (() => Date.now());
         this.logo =
@@ -95,6 +100,20 @@ export class OpenAPIManager {
         this.scanner.setRoute(route);
         return this.invalidateCache();
     }
+    /**
+     * Replaces every registered route with `routes`, for keeping the document
+     * in step with a live route table. Duplicates are rejected before anything
+     * is replaced, so a failed call leaves the previous routes in place.
+     */
+    setRoutes(routes) {
+        const next = new OpenAPIRouteScannerImpl();
+        for (const route of routes)
+            next.addRoute(route);
+        this.scanner.clear();
+        for (const route of routes)
+            this.scanner.addRoute(route);
+        return this.invalidateCache();
+    }
     /** Removes a route. Returns whether one was removed. */
     removeRoute(method, path) {
         const removed = this.scanner.removeRoute(method, path);
@@ -122,6 +141,14 @@ export class OpenAPIManager {
     schemaWarnings() {
         return this.schemas.warnings();
     }
+    /**
+     * The route warnings of the last generation, each prefixed with the route
+     * (`GET /users/:id: ...`): what could not be expressed for route-declared
+     * schemas and parameters, and operations that document no responses.
+     */
+    routeWarnings() {
+        return this.lastRouteWarnings;
+    }
     /* ── Generation ──────────────────────────────────────────────────────── */
     /**
      * Builds the document from the registered routes and components.
@@ -134,9 +161,21 @@ export class OpenAPIManager {
         // hidden, so `removeRoute()` had no effect once a document had been
         // generated.
         this.registry.clearRoutes();
-        for (const route of this.scanner.scan()) {
+        const routeWarnings = [];
+        const scanned = this.scanner.scan({
+            version: this.registry.version,
+            onWarning: (message) => {
+                routeWarnings.push(message);
+                this.onRouteWarning?.(message);
+            },
+        });
+        for (const route of scanned) {
             this.registry.setRoute(route);
         }
+        this.lastRouteWarnings = Object.freeze(routeWarnings);
+        if (routeWarnings.length > 0) {
+            this.onSchemaWarning?.("routes", this.lastRouteWarnings);
+        }
         // Brand the document unless the caller supplied a logo or opted out.
         const info = this.registry.getInfo();
         if (this.logo && !info["x-logo"]) {

package/dist/openApiRouting/index.d.ts

@@ -3,7 +3,9 @@
  *
  * Route metadata, conversion, and scanning for OpenAPI generation.
  */
-export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, OpenAPIHttpMethod, } from "./routeMetadata.type.js";
+export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, OpenAPIHttpMethod, OpenAPISchemaInput, OpenAPIRouteBody, OpenAPIRouteResponse, RouteConversionOptions, } from "./routeMetadata.type.js";
 export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, } from "./routeConverter.core.js";
 export { OpenAPIRouteScannerImpl } from "./routeScanner.core.js";
+export { buildOperationParameters } from "./routeSchema.core.js";
+export { buildOperationRequestBody, buildOperationResponses, describeResponseKey, } from "./routeContent.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiRouting/index.js

@@ -5,4 +5,6 @@
  */
 export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, } from "./routeConverter.core.js";
 export { OpenAPIRouteScannerImpl } from "./routeScanner.core.js";
+export { buildOperationParameters } from "./routeSchema.core.js";
+export { buildOperationRequestBody, buildOperationResponses, describeResponseKey, } from "./routeContent.core.js";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * 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 type { OpenAPIRequestBody, OpenAPIResponses } from "../openApiTypes/openApiTypes.core.js";
+import type { RouteConversionOptions, RouteOpenAPIMetadata } from "./routeMetadata.type.js";
+/** A default description for a response key: `404` → "Not Found". */
+export declare function describeResponseKey(key: string): string;
+/** Builds the Request Body Object from `requestBody` or `body`. */
+export declare function buildOperationRequestBody(meta: RouteOpenAPIMetadata | undefined, context: string, options?: RouteConversionOptions): OpenAPIRequestBody | undefined;
+/**
+ * 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 declare function buildOperationResponses(meta: RouteOpenAPIMetadata | undefined, context: string, options?: RouteConversionOptions): OpenAPIResponses;
+//# sourceMappingURL=routeContent.core.d.ts.map

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

@@ -66,13 +66,17 @@ export class OpenAPIRouteScannerImpl {
     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/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

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

@@ -0,0 +1,48 @@
+/**
+ * Schema-bearing inputs a route or operation may declare.
+ */
+import type { OpenAPIHeader, OpenAPIReference, OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
+import type { SchemaInputOptions } from "./schemaInput.core.js";
+/**
+ * A schema a route may declare: a `@zudojs/schema` schema (anything carrying
+ * a string `_type`, converted with `convertSchema` for the document's
+ * version), or an OpenAPI Schema / Reference Object used as-is.
+ */
+export type OpenAPISchemaInput = OpenAPISchema | OpenAPIReference | {
+    readonly _type: string;
+};
+/**
+ * A request body declared by schema rather than as a raw Request Body Object.
+ */
+export interface OpenAPIRouteBody {
+    /** The body's schema. */
+    readonly schema: OpenAPISchemaInput;
+    /** Media type(s) the body is accepted as. Default: `application/json`. */
+    readonly contentType?: string | readonly string[];
+    /** Whether the body is required. Default: `true`. */
+    readonly required?: boolean;
+    readonly description?: string;
+    readonly example?: unknown;
+}
+/**
+ * A response declared by schema rather than as a raw Response Object.
+ *
+ * An entry in `responses` is read as this shape when it has a `schema` key;
+ * otherwise it is an OpenAPI Response Object and passes through unchanged.
+ */
+export interface OpenAPIRouteResponse {
+    /** The response body's schema. */
+    readonly schema: OpenAPISchemaInput;
+    /** Default: the status code's reason phrase, e.g. "Not Found". */
+    readonly description?: string;
+    /** Media type(s) the body is sent as. Default: `application/json`. */
+    readonly contentType?: string | readonly string[];
+    readonly headers?: Readonly<Record<string, OpenAPIHeader>>;
+    readonly example?: unknown;
+}
+/**
+ * Options for converting a route into an operation: the version declared
+ * schemas are converted for, and a sink for what they could not express.
+ */
+export type RouteConversionOptions = SchemaInputOptions;
+//# sourceMappingURL=schemaInput.type.d.ts.map

package/dist/openApiSchema/schemaInput.type.js

@@ -0,0 +1,5 @@
+/**
+ * Schema-bearing inputs a route or operation may declare.
+ */
+export {};
+//# sourceMappingURL=schemaInput.type.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/openapi",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "OpenAPI 3.0 and 3.1 specification generation, validation, and serialization for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -26,13 +26,14 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.1",
-    "@zudojs/errors": "1.2.0"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.2",
+    "@zudojs/schema": "1.2.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -46,7 +47,7 @@
     "swagger",
     "api-docs"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-openapi",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },