@zudojs/openapi 1.3.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