@fluojs/openapi 1.0.3 → 2.0.0

package/dist/openapi-module.js

@@ -3,32 +3,40 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
-import { Controller, Get, NotFoundException, createHandlerMapping } from '@fluojs/http';
 import { Inject } from '@fluojs/core';
+import { Controller, createHandlerMapping, Get, NotFoundException } from '@fluojs/http';
 import { defineModule } from '@fluojs/runtime';
 import { OpenApiHandlerRegistry } from './handler-registry.js';
 import { buildOpenApiDocument } from './schema-builder.js';
 import { cloneSnapshotValue, createFrozenSnapshot } from './snapshot.js';
-const SWAGGER_UI_DIST_VERSION = '5.32.2';
-const SWAGGER_UI_DIST_BASE_URL = `https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_DIST_VERSION}`;
-const SWAGGER_UI_CSS_URL = `${SWAGGER_UI_DIST_BASE_URL}/swagger-ui.css`;
-const SWAGGER_UI_BUNDLE_JS_URL = `${SWAGGER_UI_DIST_BASE_URL}/swagger-ui-bundle.js`;
+import { createSwaggerUiHtml, resolveSwaggerUiAssets } from './swagger-ui.js';
+const DEFAULT_DOCUMENT_PATH = '/openapi.json';
+const DEFAULT_UI_PATH = '/docs';
 
 /**
- * Asset URLs used by the generated Swagger UI HTML page.
+ * Routes owned by one `OpenApiModule` registration.
+ *
+ * @remarks
+ * Paths use the normal `@fluojs/http` route grammar and are normalized before
+ * registration. The defaults remain `/openapi.json` and `/docs`.
  */
 
 /**
- * Public options for `OpenApiModule.forRoot(...)` and `OpenApiModule.forRootAsync(...)`.
+ * Public document and route options for `OpenApiModule.forRoot(...)`.
  *
  * @remarks
  * Keep README examples for full controller/module workflows. These options are
  * intended to document the runtime hooks that shape the generated document.
  */
 
-function escapeHtml(value) {
-  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#x27;');
-}
+/**
+ * Async OpenAPI registration options with routes fixed before module compilation.
+ *
+ * @remarks
+ * `documentPath` and `uiPath` belong to the outer registration because HTTP
+ * routes are compiled before the injected options factory resolves.
+ */
+
 function cloneRecord(record) {
   if (!record) {
     return undefined;
@@ -43,6 +51,7 @@ function snapshotOpenApiModuleOptions(options) {
   return createFrozenSnapshot({
     defaultErrorResponsesPolicy: options.defaultErrorResponsesPolicy,
     descriptors: options.descriptors ? cloneSnapshotValue(options.descriptors) : undefined,
+    documentPath: options.documentPath,
     documentTransform: options.documentTransform,
     extraModels: options.extraModels ? [...options.extraModels] : undefined,
     securitySchemes: cloneRecord(options.securitySchemes),
@@ -52,38 +61,17 @@ function snapshotOpenApiModuleOptions(options) {
     } : undefined,
     title: options.title,
     ui: options.ui,
+    uiPath: options.uiPath,
     version: options.version
   });
 }
-function resolveSwaggerUiAssets(options) {
+function resolveOpenApiRouteOptions(options) {
+  const normalizePath = path => `/${path.split('/').filter(Boolean).join('/')}`;
   return {
-    cssUrl: options.swaggerUiAssets?.cssUrl ?? SWAGGER_UI_CSS_URL,
-    jsBundleUrl: options.swaggerUiAssets?.jsBundleUrl ?? SWAGGER_UI_BUNDLE_JS_URL
+    documentPath: normalizePath(options.documentPath ?? DEFAULT_DOCUMENT_PATH),
+    uiPath: normalizePath(options.uiPath ?? DEFAULT_UI_PATH)
   };
 }
-function createSwaggerUiHtml(title, assets) {
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${escapeHtml(title)}</title>
-    <link rel="stylesheet" href="${escapeHtml(assets.cssUrl)}" />
-  </head>
-  <body>
-    <div id="swagger-ui"></div>
-    <script src="${escapeHtml(assets.jsBundleUrl)}" crossorigin></script>
-    <script>
-      const specUrl = window.location.pathname.replace(/\/docs\/?$/, '/openapi.json');
-      const swaggerUi = SwaggerUIBundle({
-        url: specUrl,
-        dom_id: '#swagger-ui'
-      });
-      void swaggerUi;
-    </script>
-  </body>
-</html>`;
-}
 function isOpenApiModuleOptions(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -123,10 +111,11 @@ export class OpenApiModule {
    * ```
    */
   static forRoot(options) {
+    const snapshot = snapshotOpenApiModuleOptions(options);
     return this.createModule({
       scope: 'singleton',
-      useValue: snapshotOpenApiModuleOptions(options)
-    });
+      useValue: snapshot
+    }, resolveOpenApiRouteOptions(snapshot));
   }
 
   /**
@@ -138,7 +127,9 @@ export class OpenApiModule {
    * @example
    * ```ts
    * OpenApiModule.forRootAsync({
+   *   documentPath: '/openapi/internal.json',
    *   inject: [ConfigService],
+   *   uiPath: '/docs/internal',
    *   useFactory: (config) => ({
    *     title: config.get('APP_NAME'),
    *     version: config.get('APP_VERSION'),
@@ -147,13 +138,17 @@ export class OpenApiModule {
    * ```
    */
   static forRootAsync(options) {
+    const routes = resolveOpenApiRouteOptions(options);
     return this.createModule({
       inject: options.inject,
       scope: 'singleton',
-      useFactory: async (...deps) => snapshotOpenApiModuleOptions(await options.useFactory(...deps))
-    });
+      useFactory: async (...deps) => snapshotOpenApiModuleOptions({
+        ...(await options.useFactory(...deps)),
+        ...routes
+      })
+    }, routes);
   }
-  static createModule(optionsProvider) {
+  static createModule(optionsProvider, routes) {
     let _initProto, _initClass;
     const openApiModuleOptionsToken = Symbol('fluo.openapi.module-options');
     const openApiDocumentToken = Symbol('fluo.openapi.document');
@@ -163,12 +158,12 @@ export class OpenApiModule {
         ({
           e: [_initProto],
           c: [_OpenApiController, _initClass]
-        } = _applyDecs(this, [Controller(''), Inject(openApiDocumentToken, openApiModuleOptionsToken)], [[Get('/openapi.json'), 2, "getDocument"], [Get('/docs'), 2, "getSwaggerUi"]]));
+        } = _applyDecs(this, [Controller(''), Inject(openApiDocumentToken, openApiModuleOptionsToken)], [[Get(routes.documentPath), 2, "getDocument"], [Get(routes.uiPath), 2, "getSwaggerUi"]]));
       }
       constructor(document, options) {
+        _initProto(this);
         this.document = document;
         this.options = options;
-        _initProto(this);
       }
       getDocument() {
         return cloneSnapshotValue(this.document);
@@ -178,7 +173,7 @@ export class OpenApiModule {
           throw new NotFoundException('Swagger UI is disabled.');
         }
         context.response.setHeader('content-type', 'text/html; charset=utf-8');
-        return createSwaggerUiHtml(this.options.title, resolveSwaggerUiAssets(this.options));
+        return createSwaggerUiHtml(this.options.title, resolveSwaggerUiAssets(this.options.swaggerUiAssets), routes);
       }
       static {
         _initClass();

package/dist/path-item.d.ts

@@ -0,0 +1,62 @@
+import type { OpenApiOperationObject, OpenApiParameterObject } from './schema-builder.js';
+/** Standard OpenAPI 3.1 operation keys accepted on a Path Item Object. */
+export type OpenApiOperationMethod = 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
+interface OpenApiReferenceObject {
+    $ref: string;
+    summary?: string;
+    description?: string;
+}
+interface OpenApiServerObject {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        description?: string;
+        enum?: string[];
+    }>;
+}
+/**
+ * OpenAPI Path Item Object containing standard operations, fixed fields, and specification extensions.
+ */
+export interface OpenApiPathItemObject {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    servers?: OpenApiServerObject[];
+    parameters?: (OpenApiParameterObject | OpenApiReferenceObject)[];
+    delete?: OpenApiOperationObject;
+    get?: OpenApiOperationObject;
+    head?: OpenApiOperationObject;
+    options?: OpenApiOperationObject;
+    patch?: OpenApiOperationObject;
+    post?: OpenApiOperationObject;
+    put?: OpenApiOperationObject;
+    trace?: OpenApiOperationObject;
+    [extension: `x-${string}`]: unknown;
+}
+/**
+ * Resolve one Fluo descriptor method to its standard OpenAPI operation key.
+ *
+ * @param method Descriptor method supplied by HTTP route metadata.
+ * @param path OpenAPI path used to identify invalid descriptor input.
+ * @returns The corresponding standard OpenAPI operation key.
+ * @throws {TypeError} When Fluo cannot author the descriptor method as an OpenAPI operation.
+ */
+export declare function resolveDescriptorOperationMethod(method: string, path: string): OpenApiOperationMethod;
+/**
+ * Determine whether a Path Item key is a standard OpenAPI 3.1 operation.
+ *
+ * @param key Path Item key to inspect.
+ * @returns Whether the key is a standard operation key.
+ */
+export declare function isOpenApiOperationMethod(key: string): key is OpenApiOperationMethod;
+/**
+ * Validate every transformed Path Item against the OpenAPI 3.1 key policy.
+ *
+ * @param paths Final document paths after any caller transform.
+ * @returns Nothing when every Path Item key is valid.
+ * @throws {TypeError} When a Path Item contains an unknown non-extension key.
+ */
+export declare function validateOpenApiPathItemKeys(paths: Readonly<Record<string, object>>): void;
+export {};
+//# sourceMappingURL=path-item.d.ts.map

package/dist/path-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-item.d.ts","sourceRoot":"","sources":["../src/path-item.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE1F,0EAA0E;AAC1E,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAEhH,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,mBAAmB;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,CAAC,sBAAsB,GAAG,sBAAsB,CAAC,EAAE,CAAC;IACjE,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,GAAG,CAAC,EAAE,sBAAsB,CAAC;IAC7B,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,GAAG,CAAC,EAAE,sBAAsB,CAAC;IAC7B,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC;CACrC;AAyBD;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAOrG;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,sBAAsB,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAUzF"}

package/dist/path-item.js

@@ -0,0 +1,53 @@
+/** Standard OpenAPI 3.1 operation keys accepted on a Path Item Object. */
+
+/**
+ * OpenAPI Path Item Object containing standard operations, fixed fields, and specification extensions.
+ */
+
+const OPENAPI_PATH_ITEM_FIXED_FIELDS = new Set(['$ref', 'description', 'parameters', 'servers', 'summary']);
+const DESCRIPTOR_OPERATION_METHODS = new Map([['DELETE', 'delete'], ['GET', 'get'], ['HEAD', 'head'], ['OPTIONS', 'options'], ['PATCH', 'patch'], ['POST', 'post'], ['PUT', 'put'], ['TRACE', 'trace']]);
+const OPENAPI_OPERATION_METHODS = new Set([...DESCRIPTOR_OPERATION_METHODS.values()]);
+
+/**
+ * Resolve one Fluo descriptor method to its standard OpenAPI operation key.
+ *
+ * @param method Descriptor method supplied by HTTP route metadata.
+ * @param path OpenAPI path used to identify invalid descriptor input.
+ * @returns The corresponding standard OpenAPI operation key.
+ * @throws {TypeError} When Fluo cannot author the descriptor method as an OpenAPI operation.
+ */
+export function resolveDescriptorOperationMethod(method, path) {
+  const operationMethod = DESCRIPTOR_OPERATION_METHODS.get(method);
+  if (operationMethod !== undefined) {
+    return operationMethod;
+  }
+  throw new TypeError(`OpenAPI cannot document unsupported HTTP method "${method}" for path "${path}".`);
+}
+
+/**
+ * Determine whether a Path Item key is a standard OpenAPI 3.1 operation.
+ *
+ * @param key Path Item key to inspect.
+ * @returns Whether the key is a standard operation key.
+ */
+export function isOpenApiOperationMethod(key) {
+  return OPENAPI_OPERATION_METHODS.has(key);
+}
+
+/**
+ * Validate every transformed Path Item against the OpenAPI 3.1 key policy.
+ *
+ * @param paths Final document paths after any caller transform.
+ * @returns Nothing when every Path Item key is valid.
+ * @throws {TypeError} When a Path Item contains an unknown non-extension key.
+ */
+export function validateOpenApiPathItemKeys(paths) {
+  for (const [path, pathItem] of Object.entries(paths)) {
+    for (const key of Object.keys(pathItem)) {
+      if (isOpenApiOperationMethod(key) || OPENAPI_PATH_ITEM_FIXED_FIELDS.has(key) || key.startsWith('x-')) {
+        continue;
+      }
+      throw new TypeError(`OpenAPI Path Item for path "${path}" contains unsupported key "${key}".`);
+    }
+  }
+}

package/dist/schema-bounds.d.ts

@@ -0,0 +1,9 @@
+import type { OpenApiDocument } from './schema-builder.js';
+/**
+ * Normalize legacy exclusive-bound and nullable metadata before an OpenAPI 3.1 document is exposed.
+ *
+ * @param document Generated document, including any final caller transform.
+ * @returns A detached document whose schema keywords use OpenAPI 3.1 forms.
+ */
+export declare function normalizeOpenApiDocumentSchemaBounds(document: OpenApiDocument): OpenApiDocument;
+//# sourceMappingURL=schema-bounds.d.ts.map

package/dist/schema-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bounds.d.ts","sourceRoot":"","sources":["../src/schema-bounds.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,qBAAqB,CAAC;AAuP7B;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAiB/F"}

package/dist/schema-bounds.js

@@ -0,0 +1,175 @@
+import { isOpenApiOperationMethod } from './path-item.js';
+function normalizeSchemaRecord(schemas, path, normalizedSchemas) {
+  const normalized = {};
+  for (const [name, schema] of Object.entries(schemas)) {
+    normalized[name] = normalizeOpenApiSchemaBounds(schema, `${path}.${name}`, normalizedSchemas);
+  }
+  return normalized;
+}
+function normalizeSchemaList(schemas, path, normalizedSchemas) {
+  return schemas.map((schema, index) => normalizeOpenApiSchemaBounds(schema, `${path}[${String(index)}]`, normalizedSchemas));
+}
+function normalizeOpenApiSchemaBounds(schema, path, normalizedSchemas) {
+  const cachedSchema = normalizedSchemas.get(schema);
+  if (cachedSchema) {
+    return cachedSchema;
+  }
+  if (schema.nullable === true && schema.type === undefined) {
+    const nullableUnion = {};
+    const nonNullableSchema = {
+      ...schema
+    };
+    delete nonNullableSchema.nullable;
+    normalizedSchemas.set(schema, nullableUnion);
+    nullableUnion.anyOf = [normalizeOpenApiSchemaBounds(nonNullableSchema, `${path}.anyOf[0]`, normalizedSchemas), {
+      type: 'null'
+    }];
+    return nullableUnion;
+  }
+  const normalized = {
+    ...schema
+  };
+  normalizedSchemas.set(schema, normalized);
+  if (typeof schema.nullable === 'boolean') {
+    delete normalized.nullable;
+  }
+  if (schema.nullable === true && schema.type !== undefined) {
+    normalized.type = typeof schema.type === 'string' ? schema.type === 'null' ? 'null' : [schema.type, 'null'] : schema.type.includes('null') ? schema.type : [...schema.type, 'null'];
+  }
+  if (typeof schema.exclusiveMinimum === 'number' && !Number.isFinite(schema.exclusiveMinimum)) {
+    throw new TypeError(`OpenAPI schema ${path}.exclusiveMinimum must be a finite number.`);
+  }
+  if (typeof schema.exclusiveMinimum === 'boolean') {
+    delete normalized.exclusiveMinimum;
+    if (schema.exclusiveMinimum) {
+      if (schema.minimum === undefined || !Number.isFinite(schema.minimum)) {
+        throw new TypeError(`OpenAPI schema ${path}.exclusiveMinimum requires a finite minimum.`);
+      }
+      normalized.exclusiveMinimum = schema.minimum;
+      delete normalized.minimum;
+    }
+  }
+  if (typeof schema.exclusiveMaximum === 'number' && !Number.isFinite(schema.exclusiveMaximum)) {
+    throw new TypeError(`OpenAPI schema ${path}.exclusiveMaximum must be a finite number.`);
+  }
+  if (typeof schema.exclusiveMaximum === 'boolean') {
+    delete normalized.exclusiveMaximum;
+    if (schema.exclusiveMaximum) {
+      if (schema.maximum === undefined || !Number.isFinite(schema.maximum)) {
+        throw new TypeError(`OpenAPI schema ${path}.exclusiveMaximum requires a finite maximum.`);
+      }
+      normalized.exclusiveMaximum = schema.maximum;
+      delete normalized.maximum;
+    }
+  }
+  if (schema.allOf) {
+    normalized.allOf = normalizeSchemaList(schema.allOf, `${path}.allOf`, normalizedSchemas);
+  }
+  if (schema.oneOf) {
+    normalized.oneOf = normalizeSchemaList(schema.oneOf, `${path}.oneOf`, normalizedSchemas);
+  }
+  if (schema.anyOf) {
+    normalized.anyOf = normalizeSchemaList(schema.anyOf, `${path}.anyOf`, normalizedSchemas);
+  }
+  if (schema.not) {
+    normalized.not = normalizeOpenApiSchemaBounds(schema.not, `${path}.not`, normalizedSchemas);
+  }
+  if (schema.properties) {
+    normalized.properties = normalizeSchemaRecord(schema.properties, `${path}.properties`, normalizedSchemas);
+  }
+  if (schema.items) {
+    normalized.items = normalizeOpenApiSchemaBounds(schema.items, `${path}.items`, normalizedSchemas);
+  }
+  if (typeof schema.additionalProperties === 'object') {
+    normalized.additionalProperties = normalizeOpenApiSchemaBounds(schema.additionalProperties, `${path}.additionalProperties`, normalizedSchemas);
+  }
+  return normalized;
+}
+function normalizeContent(content, path, normalizedSchemas) {
+  const normalized = {};
+  for (const [mediaType, media] of Object.entries(content)) {
+    normalized[mediaType] = {
+      ...media,
+      schema: normalizeOpenApiSchemaBounds(media.schema, `${path}.${mediaType}.schema`, normalizedSchemas)
+    };
+  }
+  return normalized;
+}
+function normalizeResponses(responses, path, normalizedSchemas) {
+  const normalized = {};
+  for (const [status, response] of Object.entries(responses)) {
+    normalized[status] = {
+      ...response,
+      ...(response.content ? {
+        content: normalizeContent(response.content, `${path}.${status}.content`, normalizedSchemas)
+      } : {})
+    };
+  }
+  return normalized;
+}
+function normalizeOperation(operation, path, normalizedSchemas) {
+  return {
+    ...operation,
+    ...(operation.parameters ? {
+      parameters: operation.parameters.map((parameter, index) => ({
+        ...parameter,
+        schema: normalizeOpenApiSchemaBounds(parameter.schema, `${path}.parameters[${String(index)}].schema`, normalizedSchemas)
+      }))
+    } : {}),
+    ...(operation.requestBody ? {
+      requestBody: {
+        ...operation.requestBody,
+        content: normalizeContent(operation.requestBody.content, `${path}.requestBody.content`, normalizedSchemas)
+      }
+    } : {}),
+    responses: normalizeResponses(operation.responses, `${path}.responses`, normalizedSchemas)
+  };
+}
+function normalizePaths(paths, normalizedSchemas) {
+  const normalizedPaths = {};
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const normalizedPathItem = {};
+    if (pathItem.parameters) {
+      normalizedPathItem.parameters = pathItem.parameters.map((parameter, index) => 'schema' in parameter ? {
+        ...parameter,
+        schema: normalizeOpenApiSchemaBounds(parameter.schema, `paths.${path}.parameters[${String(index)}].schema`, normalizedSchemas)
+      } : {
+        ...parameter
+      });
+    }
+    for (const [key, value] of Object.entries(pathItem)) {
+      if (key === 'parameters') {
+        continue;
+      }
+      if (isOpenApiOperationMethod(key)) {
+        normalizedPathItem[key] = value ? normalizeOperation(value, `paths.${path}.${key}`, normalizedSchemas) : undefined;
+        continue;
+      }
+      Reflect.set(normalizedPathItem, key, value);
+    }
+    normalizedPaths[path] = normalizedPathItem;
+  }
+  return normalizedPaths;
+}
+
+/**
+ * Normalize legacy exclusive-bound and nullable metadata before an OpenAPI 3.1 document is exposed.
+ *
+ * @param document Generated document, including any final caller transform.
+ * @returns A detached document whose schema keywords use OpenAPI 3.1 forms.
+ */
+export function normalizeOpenApiDocumentSchemaBounds(document) {
+  const normalizedSchemas = new WeakMap();
+  return {
+    ...document,
+    ...(document.components ? {
+      components: {
+        ...document.components,
+        ...(document.components.schemas ? {
+          schemas: normalizeSchemaRecord(document.components.schemas, 'components.schemas', normalizedSchemas)
+        } : {})
+      }
+    } : {}),
+    paths: normalizePaths(document.paths, normalizedSchemas)
+  };
+}

package/dist/schema-builder.d.ts

@@ -1,5 +1,7 @@
 import type { Constructor } from '@fluojs/core';
 import type { HandlerDescriptor } from '@fluojs/http';
+import { type OpenApiPathItemObject } from './path-item.js';
+export type { OpenApiPathItemObject } from './path-item.js';
 /**
  * JSON Schema primitive type names accepted by OpenAPI 3.1 schema objects.
  */
@@ -52,6 +54,7 @@ export interface OpenApiSchemaObject {
     deprecated?: boolean;
     readOnly?: boolean;
     writeOnly?: boolean;
+    /** Legacy compatibility input normalized to an OpenAPI 3.1 null union before emission. */
     nullable?: boolean;
     minimum?: number;
     maximum?: number;
@@ -147,12 +150,6 @@ export interface OpenApiOperationObject {
     requestBody?: OpenApiRequestBodyObject;
     security?: OpenApiSecurityRequirementObject[];
 }
-/**
- * OpenAPI path-item object containing one or more HTTP method operations.
- */
-export interface OpenApiPathItemObject {
-    [method: string]: OpenApiOperationObject | undefined;
-}
 /**
  * Root OpenAPI 3.1.0 document produced by `buildOpenApiDocument(...)`.
  */

package/dist/schema-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-builder.d.ts","sourceRoot":"","sources":["../src/schema-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-builder.d.ts","sourceRoot":"","sources":["../src/schema-builder.ts"],"names":[],"mappings":"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"}

package/dist/schema-builder.js

@@ -1,5 +1,7 @@
-import { getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/internal';
+import { getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/request-pipeline';
 import { getControllerTags, getMethodApiMetadata } from './decorators.js';
+import { resolveDescriptorOperationMethod, validateOpenApiPathItemKeys } from './path-item.js';
+import { normalizeOpenApiDocumentSchemaBounds } from './schema-bounds.js';
 import { cloneSnapshotValue } from './snapshot.js';
 
 /**
@@ -46,10 +48,6 @@ import { cloneSnapshotValue } from './snapshot.js';
  * OpenAPI operation object emitted for a single HTTP method on a path.
  */
 
-/**
- * OpenAPI path-item object containing one or more HTTP method operations.
- */
-
 /**
  * Root OpenAPI 3.1.0 document produced by `buildOpenApiDocument(...)`.
  */
@@ -491,12 +489,9 @@ function ensureComponentSchema(dto, componentSchemas, context) {
   const schemaName = getDtoSchemaName(dto, context);
   return ensureComponentSchemaFromEntries(schemaName, collectDtoEntries(dto, context), componentSchemas, context);
 }
-function createParameters(dto, context) {
-  if (!dto) {
-    return [];
-  }
-  const entries = collectDtoEntries(dto, context).filter(entry => entry.binding?.metadata.source === 'path' || entry.binding?.metadata.source === 'query' || entry.binding?.metadata.source === 'header' || entry.binding?.metadata.source === 'cookie');
-  return entries.map(entry => {
+function createParameters(dto, routePath, context) {
+  const entries = dto ? collectDtoEntries(dto, context).filter(entry => entry.binding?.metadata.source === 'path' || entry.binding?.metadata.source === 'query' || entry.binding?.metadata.source === 'header' || entry.binding?.metadata.source === 'cookie') : [];
+  const parameters = entries.map(entry => {
     const source = entry.binding.metadata.source;
     const rules = entry.validation?.rules ?? [];
     const inferred = inferPrimitiveTypeFromRules(rules, context) ?? {};
@@ -509,6 +504,22 @@ function createParameters(dto, context) {
       schema
     };
   });
+  const documentedPathParameters = new Set(parameters.filter(parameter => parameter.in === 'path').map(parameter => parameter.name));
+  for (const match of routePath.matchAll(/:([a-zA-Z_][a-zA-Z0-9_]*)/g)) {
+    const name = match[1];
+    if (!documentedPathParameters.has(name)) {
+      documentedPathParameters.add(name);
+      parameters.push({
+        in: 'path',
+        name,
+        required: true,
+        schema: {
+          type: 'string'
+        }
+      });
+    }
+  }
+  return parameters;
 }
 function ensureErrorResponseSchema(componentSchemas) {
   const schemaName = 'ErrorResponse';
@@ -785,7 +796,7 @@ function hasBearerAuthRequirement(security) {
   return Boolean(security?.some(requirement => Object.keys(requirement).includes('bearerAuth')));
 }
 function createOperationObject(descriptor, methodMeta, responses, componentSchemas, security, context, usedOperationIds) {
-  const parameters = mergeOperationParameters(createParameters(descriptor.route.request, context), methodMeta?.parameters);
+  const parameters = mergeOperationParameters(createParameters(descriptor.route.request, descriptor.route.path, context), methodMeta?.parameters);
   const requestBody = mergeOperationRequestBody(createRequestBody(descriptor.route.request, componentSchemas, context), methodMeta);
   return {
     operationId: resolveUniqueOperationId(normalizeOperationId(descriptor), usedOperationIds),
@@ -813,11 +824,11 @@ function createOperationObject(descriptor, methodMeta, responses, componentSchem
 }
 function buildOperationEntry(descriptor, componentSchemas, defaultErrorResponsesPolicy, context, usedOperationIds) {
   const openApiPath = expressPathToOpenApi(descriptor.route.path);
-  const method = descriptor.route.method.toLowerCase();
   const methodMeta = getMethodApiMetadata(descriptor.controllerToken, descriptor.methodName);
   if (methodMeta?.excludeEndpoint === true) {
     return undefined;
   }
+  const method = resolveDescriptorOperationMethod(descriptor.route.method, openApiPath);
   const responses = createOperationResponses(descriptor, methodMeta, componentSchemas, defaultErrorResponsesPolicy, context);
   const security = createOperationSecurity(methodMeta);
   const operation = createOperationObject(descriptor, methodMeta, responses, componentSchemas, security, context, usedOperationIds);
@@ -917,5 +928,7 @@ export function buildOpenApiDocument(options) {
     openapi: '3.1.0',
     paths
   };
-  return options.documentTransform ? options.documentTransform(document) : document;
+  const transformedDocument = options.documentTransform ? options.documentTransform(document) : document;
+  validateOpenApiPathItemKeys(transformedDocument.paths);
+  return normalizeOpenApiDocumentSchemaBounds(transformedDocument);
 }

package/dist/swagger-ui.d.ts

@@ -0,0 +1,29 @@
+type SwaggerUiRoutes = {
+    readonly documentPath: string;
+    readonly uiPath: string;
+};
+/**
+ * Asset URLs used by the generated Swagger UI HTML page.
+ */
+export interface OpenApiSwaggerUiAssetsOptions {
+    cssUrl?: string;
+    jsBundleUrl?: string;
+}
+/**
+ * Resolve pinned or caller-provided Swagger UI asset URLs.
+ *
+ * @param assets Optional caller-provided asset URLs.
+ * @returns Complete asset URLs for generated Swagger UI HTML.
+ */
+export declare function resolveSwaggerUiAssets(assets: OpenApiSwaggerUiAssetsOptions | undefined): Required<OpenApiSwaggerUiAssetsOptions>;
+/**
+ * Render Swagger UI HTML for one configured OpenAPI document route.
+ *
+ * @param title Document title rendered into the page.
+ * @param assets Complete Swagger UI asset URLs.
+ * @param routes Normalized JSON document and UI routes.
+ * @returns A standalone Swagger UI HTML document.
+ */
+export declare function createSwaggerUiHtml(title: string, assets: Required<OpenApiSwaggerUiAssetsOptions>, routes: SwaggerUiRoutes): string;
+export {};
+//# sourceMappingURL=swagger-ui.d.ts.map

package/dist/swagger-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger-ui.d.ts","sourceRoot":"","sources":["../src/swagger-ui.ts"],"names":[],"mappings":"AAKA,KAAK,eAAe,GAAG;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAsBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,6BAA6B,GAAG,SAAS,GAChD,QAAQ,CAAC,6BAA6B,CAAC,CAKzC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,QAAQ,CAAC,6BAA6B,CAAC,EAC/C,MAAM,EAAE,eAAe,GACtB,MAAM,CA6BR"}