@fluojs/openapi 1.0.0-beta.1

package/dist/schema-builder.js

@@ -0,0 +1,877 @@
+import { getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/internal';
+import { getControllerTags, getMethodApiMetadata } from './decorators.js';
+
+/**
+ * OpenAPI `info` object emitted in the generated document.
+ */
+
+/**
+ * OpenAPI response object emitted for an operation status code.
+ */
+
+/**
+ * OpenAPI security requirement object emitted on an operation.
+ */
+
+/**
+ * JSON Schema-compatible OpenAPI schema object used across parameters, bodies, and components.
+ */
+
+/**
+ * OpenAPI parameter object emitted for path, query, header, or cookie bindings.
+ */
+
+/**
+ * OpenAPI media-type object wrapping a schema.
+ */
+
+/**
+ * OpenAPI request-body object emitted for handler body bindings.
+ */
+
+/**
+ * OpenAPI security scheme object registered in `components.securitySchemes`.
+ */
+
+/**
+ * OpenAPI components object emitted for shared schemas and security schemes.
+ */
+
+/**
+ * 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(...)`.
+ */
+
+/**
+ * Input used by `buildOpenApiDocument(...)` to assemble an OpenAPI document.
+ *
+ * @remarks
+ * Most applications should prefer `OpenApiModule.forRoot(...)`. Use this lower
+ * level builder when tests or custom tooling need a document without mounting
+ * the OpenAPI runtime module.
+ */
+
+/**
+ * Controls whether common framework error responses are injected automatically.
+ */
+
+function expressPathToOpenApi(path) {
+  return path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}');
+}
+function resolveControllerTags(descriptor) {
+  const decorated = getControllerTags(descriptor.controllerToken);
+  if (decorated && decorated.length > 0) {
+    return decorated;
+  }
+  return [descriptor.controllerToken.name || 'Controller'];
+}
+function normalizeOperationId(descriptor) {
+  const tag = resolveControllerTags(descriptor)[0] ?? 'Controller';
+  const path = expressPathToOpenApi(descriptor.route.path).replaceAll('/', '_').replaceAll('{', '').replaceAll('}', '').replaceAll('-', '_');
+  return `${tag}_${descriptor.methodName}_${descriptor.route.method.toLowerCase()}${path}`;
+}
+function propertyName(propertyKey) {
+  return typeof propertyKey === 'string' ? propertyKey : String(propertyKey);
+}
+function collectDtoEntries(dto, context) {
+  const cachedEntries = context.dtoEntries.get(dto);
+  if (cachedEntries) {
+    return cachedEntries;
+  }
+  const bindingEntries = getDtoBindingSchema(dto);
+  const validationEntries = getDtoValidationSchema(dto);
+  const bindingMap = new Map(bindingEntries.map(entry => [entry.propertyKey, entry]));
+  const validationMap = new Map(validationEntries.map(entry => [entry.propertyKey, entry]));
+  const propertyKeys = new Set([...Array.from(bindingMap.keys()), ...Array.from(validationMap.keys())]);
+  const entries = Array.from(propertyKeys).map(propertyKey => ({
+    binding: bindingMap.get(propertyKey),
+    name: propertyName(propertyKey),
+    validation: validationMap.get(propertyKey)
+  }));
+  context.dtoEntries.set(dto, entries);
+  return entries;
+}
+function getDtoSchemaName(dto, context, suffix = '') {
+  let perDto = context.dtoSchemaNames.get(dto);
+  if (!perDto) {
+    perDto = new Map();
+    context.dtoSchemaNames.set(dto, perDto);
+  }
+  const cached = perDto.get(suffix);
+  if (cached) {
+    return cached;
+  }
+  const baseName = `${dto.name || 'AnonymousDto'}${suffix}`;
+  let candidate = baseName;
+  let index = 2;
+  while (context.usedSchemaNames.has(candidate)) {
+    candidate = `${baseName}_${String(index)}`;
+    index++;
+  }
+  context.usedSchemaNames.add(candidate);
+  perDto.set(suffix, candidate);
+  return candidate;
+}
+function createSchemaRef(name) {
+  return {
+    $ref: `#/components/schemas/${name}`
+  };
+}
+function resolveNestedDto(dto) {
+  if (typeof dto === 'function' && 'prototype' in dto && dto.prototype) {
+    return dto;
+  }
+  return dto();
+}
+function inferEnumValueType(value) {
+  if (typeof value === 'number') {
+    return 'number';
+  }
+  if (typeof value === 'boolean') {
+    return 'boolean';
+  }
+  return 'string';
+}
+function createEnumSchema(values) {
+  const typeSet = new Set(values.map(value => inferEnumValueType(value)));
+  return {
+    enum: [...values],
+    ...(typeSet.size === 1 && values.length > 0 ? {
+      type: inferEnumValueType(values[0])
+    } : {})
+  };
+}
+function inferNestedSchema(nestedRule, context) {
+  if (!nestedRule) {
+    return undefined;
+  }
+  const resolvedDto = resolveNestedDto(nestedRule.dto);
+  const schemaName = getDtoSchemaName(resolvedDto, context);
+  if (nestedRule.each) {
+    return {
+      items: createSchemaRef(schemaName),
+      type: 'array'
+    };
+  }
+  return createSchemaRef(schemaName);
+}
+const ruleProfileCache = new WeakMap();
+function resolveValidatorStringFormat(validatorRule) {
+  if (validatorRule.validator === 'email') {
+    return 'email';
+  }
+  if (validatorRule.validator === 'uuid') {
+    return 'uuid';
+  }
+  if (validatorRule.validator === 'url') {
+    return 'uri';
+  }
+  if (validatorRule.validator === 'dateString' || validatorRule.validator === 'iso8601') {
+    return 'date-time';
+  }
+  return undefined;
+}
+function createRuleProfile() {
+  return {
+    enumEachRule: undefined,
+    enumRule: undefined,
+    hasArrayRule: false,
+    hasBooleanRule: false,
+    hasDateRule: false,
+    hasEachBooleanRule: false,
+    hasEachIntRule: false,
+    hasEachNumberRule: false,
+    hasIntRule: false,
+    hasNumberRule: false,
+    hasObjectRule: false,
+    hasStringRule: false,
+    hasStringRuleForEach: false,
+    maxLength: undefined,
+    maximum: undefined,
+    minLength: undefined,
+    minimum: undefined,
+    nestedEachRule: undefined,
+    nestedRule: undefined,
+    stringFormat: undefined
+  };
+}
+function applyRuleToProfile(profile, rule) {
+  if (rule.kind === 'nested') {
+    profile.nestedRule ??= rule;
+    if (rule.each) {
+      profile.nestedEachRule ??= rule;
+    }
+    return;
+  }
+  if (rule.kind === 'array') {
+    profile.hasArrayRule = true;
+    return;
+  }
+  if (rule.kind === 'enum') {
+    profile.enumRule ??= rule;
+    if (rule.each) {
+      profile.enumEachRule ??= rule;
+    }
+    return;
+  }
+  if (rule.kind === 'int') {
+    profile.hasIntRule = true;
+    if (rule.each) {
+      profile.hasEachIntRule = true;
+    }
+    return;
+  }
+  if (rule.kind === 'number') {
+    profile.hasNumberRule = true;
+    if (rule.each) {
+      profile.hasEachNumberRule = true;
+    }
+    return;
+  }
+  if (rule.kind === 'boolean') {
+    profile.hasBooleanRule = true;
+    if (rule.each) {
+      profile.hasEachBooleanRule = true;
+    }
+    return;
+  }
+  if (rule.kind === 'date') {
+    profile.hasDateRule = true;
+    return;
+  }
+  if (rule.kind === 'object') {
+    profile.hasObjectRule = true;
+    return;
+  }
+  if (rule.kind === 'string') {
+    profile.hasStringRule = true;
+    return;
+  }
+  if (rule.kind === 'minLength') {
+    if (rule.each) {
+      profile.hasStringRuleForEach = true;
+      return;
+    }
+    profile.minLength = rule.value;
+    return;
+  }
+  if (rule.kind === 'maxLength') {
+    if (rule.each) {
+      profile.hasStringRuleForEach = true;
+      return;
+    }
+    profile.maxLength = rule.value;
+    return;
+  }
+  if (rule.kind === 'min' && !rule.each) {
+    profile.minimum = rule.value;
+    return;
+  }
+  if (rule.kind === 'max' && !rule.each) {
+    profile.maximum = rule.value;
+    return;
+  }
+  if (rule.kind === 'validatorjs') {
+    const nextFormat = resolveValidatorStringFormat(rule);
+    if (nextFormat) {
+      profile.stringFormat = nextFormat;
+    }
+  }
+}
+function getRuleProfile(rules) {
+  const cached = ruleProfileCache.get(rules);
+  if (cached) {
+    return cached;
+  }
+  const profile = createRuleProfile();
+  for (const rule of rules) {
+    applyRuleToProfile(profile, rule);
+  }
+  ruleProfileCache.set(rules, profile);
+  return profile;
+}
+function inferPrimitiveTypeFromRules(rules, context) {
+  const profile = getRuleProfile(rules);
+  const nestedSchema = inferNestedSchema(profile.nestedRule, context);
+  if (nestedSchema) {
+    return nestedSchema;
+  }
+  if (profile.hasArrayRule) {
+    return {
+      items: inferEachItemSchema(rules, context, profile) ?? {},
+      type: 'array'
+    };
+  }
+  if (profile.enumRule) {
+    return createEnumSchema(profile.enumRule.values);
+  }
+  if (profile.hasIntRule) {
+    return {
+      type: 'integer'
+    };
+  }
+  if (profile.hasNumberRule) {
+    return {
+      type: 'number'
+    };
+  }
+  if (profile.hasBooleanRule) {
+    return {
+      type: 'boolean'
+    };
+  }
+  if (profile.hasDateRule) {
+    return {
+      format: 'date-time',
+      type: 'string'
+    };
+  }
+  if (profile.hasObjectRule) {
+    return {
+      additionalProperties: true,
+      type: 'object'
+    };
+  }
+  if (profile.hasStringRule) {
+    return {
+      type: 'string'
+    };
+  }
+  return undefined;
+}
+function inferEachItemSchema(rules, context, profile = getRuleProfile(rules)) {
+  if (profile.nestedEachRule) {
+    const resolvedDto = resolveNestedDto(profile.nestedEachRule.dto);
+    return createSchemaRef(getDtoSchemaName(resolvedDto, context));
+  }
+  if (profile.enumEachRule) {
+    return createEnumSchema(profile.enumEachRule.values);
+  }
+  if (profile.hasStringRule || profile.hasStringRuleForEach) {
+    return {
+      type: 'string'
+    };
+  }
+  if (profile.hasEachIntRule) {
+    return {
+      type: 'integer'
+    };
+  }
+  if (profile.hasEachNumberRule) {
+    return {
+      type: 'number'
+    };
+  }
+  if (profile.hasEachBooleanRule) {
+    return {
+      type: 'boolean'
+    };
+  }
+  return undefined;
+}
+function applyValidationConstraints(schema, rules) {
+  const nextSchema = {
+    ...schema
+  };
+  const profile = getRuleProfile(rules);
+  if (nextSchema.type === 'string') {
+    if (profile.minLength !== undefined) {
+      nextSchema.minLength = profile.minLength;
+    }
+    if (profile.maxLength !== undefined) {
+      nextSchema.maxLength = profile.maxLength;
+    }
+    if (profile.stringFormat !== undefined) {
+      nextSchema.format = profile.stringFormat;
+    }
+  }
+  if (nextSchema.type === 'number' || nextSchema.type === 'integer') {
+    if (profile.minimum !== undefined) {
+      nextSchema.minimum = profile.minimum;
+    }
+    if (profile.maximum !== undefined) {
+      nextSchema.maximum = profile.maximum;
+    }
+  }
+  return nextSchema;
+}
+function isPropertyRequired(binding, validation) {
+  if (binding?.metadata.optional) {
+    return false;
+  }
+  if (validation?.rules.some(rule => rule.kind === 'optional')) {
+    return false;
+  }
+  return true;
+}
+function ensureComponentSchemaFromEntries(schemaName, entries, componentSchemas, context) {
+  if (componentSchemas[schemaName]) {
+    return createSchemaRef(schemaName);
+  }
+  componentSchemas[schemaName] = {
+    additionalProperties: false,
+    properties: {},
+    type: 'object'
+  };
+  const {
+    properties,
+    required
+  } = buildComponentSchemaShape(entries, componentSchemas, context);
+  componentSchemas[schemaName] = {
+    additionalProperties: false,
+    properties,
+    ...(required.length > 0 && {
+      required
+    }),
+    type: 'object'
+  };
+  return createSchemaRef(schemaName);
+}
+function ensureNestedSchemasFromRules(rules, componentSchemas, context) {
+  for (const rule of rules) {
+    if (rule.kind === 'nested') {
+      ensureComponentSchema(resolveNestedDto(rule.dto), componentSchemas, context);
+    }
+  }
+}
+function buildComponentSchemaShape(entries, componentSchemas, context) {
+  const properties = {};
+  const required = [];
+  for (const entry of entries) {
+    const rules = entry.validation?.rules ?? [];
+    ensureNestedSchemasFromRules(rules, componentSchemas, context);
+    const inferred = inferPrimitiveTypeFromRules(rules, context) ?? {};
+    properties[entry.name] = applyValidationConstraints(inferred, rules);
+    if (isPropertyRequired(entry.binding, entry.validation)) {
+      required.push(entry.name);
+    }
+  }
+  return {
+    properties,
+    required
+  };
+}
+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 => {
+    const source = entry.binding.metadata.source;
+    const rules = entry.validation?.rules ?? [];
+    const inferred = inferPrimitiveTypeFromRules(rules, context) ?? {};
+    const schema = alignParameterSchemaWithRuntimeBindingContract(applyValidationConstraints(inferred, rules), source);
+    const isRequired = source === 'path' ? true : isPropertyRequired(entry.binding, entry.validation);
+    return {
+      in: source,
+      name: entry.binding.metadata.key ?? entry.name,
+      required: isRequired,
+      schema
+    };
+  });
+}
+function ensureErrorResponseSchema(componentSchemas) {
+  const schemaName = 'ErrorResponse';
+  if (!componentSchemas[schemaName]) {
+    componentSchemas[schemaName] = {
+      additionalProperties: false,
+      properties: {
+        error: {
+          additionalProperties: false,
+          properties: {
+            code: {
+              type: 'string'
+            },
+            details: {
+              items: {
+                additionalProperties: false,
+                properties: {
+                  code: {
+                    type: 'string'
+                  },
+                  field: {
+                    type: 'string'
+                  },
+                  message: {
+                    type: 'string'
+                  },
+                  source: {
+                    enum: ['path', 'query', 'header', 'cookie', 'body'],
+                    type: 'string'
+                  }
+                },
+                required: ['code', 'message'],
+                type: 'object'
+              },
+              type: 'array'
+            },
+            message: {
+              type: 'string'
+            },
+            meta: {
+              additionalProperties: true,
+              type: 'object'
+            },
+            requestId: {
+              type: 'string'
+            },
+            status: {
+              type: 'integer'
+            }
+          },
+          required: ['code', 'status', 'message'],
+          type: 'object'
+        }
+      },
+      required: ['error'],
+      type: 'object'
+    };
+  }
+  return createSchemaRef(schemaName);
+}
+function addDefaultErrorResponses(responses, componentSchemas) {
+  const errorSchema = ensureErrorResponseSchema(componentSchemas);
+  const defaultErrorResponses = {
+    '400': 'Bad Request',
+    '401': 'Unauthorized',
+    '403': 'Forbidden',
+    '404': 'Not Found',
+    '500': 'Internal Server Error'
+  };
+  for (const [status, description] of Object.entries(defaultErrorResponses)) {
+    if (responses[status]) {
+      continue;
+    }
+    responses[status] = {
+      content: {
+        'application/json': {
+          schema: errorSchema
+        }
+      },
+      description
+    };
+  }
+}
+function createRequestBody(dto, componentSchemas, context) {
+  if (!dto) {
+    return undefined;
+  }
+  const dtoEntries = collectDtoEntries(dto, context);
+  const entries = dtoEntries.filter(entry => entry.binding?.metadata.source === 'body');
+  if (entries.length === 0) {
+    return undefined;
+  }
+  const schemaName = entries.length === dtoEntries.length ? getDtoSchemaName(dto, context) : getDtoSchemaName(dto, context, 'RequestBody');
+  ensureComponentSchemaFromEntries(schemaName, entries, componentSchemas, context);
+  return {
+    content: {
+      'application/json': {
+        schema: createSchemaRef(schemaName)
+      }
+    },
+    ...(entries.some(entry => isPropertyRequired(entry.binding, entry.validation)) ? {
+      required: true
+    } : {})
+  };
+}
+function createExplicitRequestBody(methodMeta) {
+  const requestBodyMeta = methodMeta?.requestBody;
+  if (!requestBodyMeta) {
+    return undefined;
+  }
+  const content = requestBodyMeta.content ? requestBodyMeta.content : requestBodyMeta.schema ? {
+    'application/json': {
+      schema: requestBodyMeta.schema
+    }
+  } : undefined;
+  if (!content) {
+    return undefined;
+  }
+  return {
+    content,
+    ...(requestBodyMeta.description !== undefined ? {
+      description: requestBodyMeta.description
+    } : {}),
+    ...(requestBodyMeta.required !== undefined ? {
+      required: requestBodyMeta.required
+    } : {})
+  };
+}
+function scalarizeArraySchemaItems(items) {
+  if (!items || items.$ref !== undefined || items.type === undefined || items.type === 'array' || items.type === 'object') {
+    return {
+      type: 'string'
+    };
+  }
+  return {
+    type: items.type,
+    ...(items.format !== undefined && {
+      format: items.format
+    }),
+    ...(items.enum !== undefined && {
+      enum: items.enum
+    })
+  };
+}
+function alignParameterSchemaWithRuntimeBindingContract(schema, source) {
+  let aligned = schema;
+  if (aligned.$ref !== undefined) {
+    aligned = {
+      type: 'string'
+    };
+  }
+  if (aligned.type === 'object') {
+    aligned = {
+      type: 'string'
+    };
+  }
+  if (aligned.type === 'array' && aligned.items) {
+    if (aligned.items.$ref !== undefined || aligned.items.type === 'object') {
+      aligned = {
+        ...aligned,
+        items: {
+          type: 'string'
+        }
+      };
+    }
+  }
+  if ((source === 'path' || source === 'cookie') && aligned.type === 'array') {
+    return scalarizeArraySchemaItems(aligned.items);
+  }
+  return aligned;
+}
+function createExplicitParameter(parameter) {
+  const source = parameter.in;
+  const schema = alignParameterSchemaWithRuntimeBindingContract(parameter.schema ?? {
+    type: 'string'
+  }, source);
+  const isRequired = source === 'path' ? true : parameter.required;
+  return {
+    in: source,
+    name: parameter.name,
+    ...(parameter.description !== undefined ? {
+      description: parameter.description
+    } : {}),
+    ...(isRequired !== undefined ? {
+      required: isRequired
+    } : {}),
+    schema
+  };
+}
+function mergeOperationParameters(inferred, explicit) {
+  if (!explicit || explicit.length === 0) {
+    return inferred;
+  }
+  const merged = new Map();
+  for (const parameter of inferred) {
+    merged.set(`${parameter.in}:${parameter.name}`, parameter);
+  }
+  for (const parameter of explicit) {
+    const explicitParameter = createExplicitParameter(parameter);
+    merged.set(`${explicitParameter.in}:${explicitParameter.name}`, explicitParameter);
+  }
+  return Array.from(merged.values());
+}
+function mergeOperationRequestBody(inferred, methodMeta) {
+  const explicit = createExplicitRequestBody(methodMeta);
+  if (!explicit) {
+    return inferred;
+  }
+  if (!inferred) {
+    return explicit;
+  }
+  return {
+    ...inferred,
+    ...explicit
+  };
+}
+function createResponseObject(response, componentSchemas, context) {
+  const schema = response.schema ? response.schema : response.type ? ensureComponentSchema(response.type, componentSchemas, context) : undefined;
+  return {
+    description: response.description ?? 'OK',
+    ...(schema ? {
+      content: {
+        'application/json': {
+          schema
+        }
+      }
+    } : {})
+  };
+}
+function createOperationResponses(descriptor, methodMeta, componentSchemas, defaultErrorResponsesPolicy, context) {
+  const responses = {};
+  if (methodMeta?.responses && methodMeta.responses.length > 0) {
+    for (const response of methodMeta.responses) {
+      responses[String(response.status)] = createResponseObject(response, componentSchemas, context);
+    }
+  } else {
+    responses[String(descriptor.route.successStatus ?? 200)] = {
+      description: 'OK'
+    };
+  }
+  if (defaultErrorResponsesPolicy === 'inject') {
+    addDefaultErrorResponses(responses, componentSchemas);
+  }
+  return responses;
+}
+function createOperationSecurity(methodMeta) {
+  if (methodMeta?.securityRequirements && methodMeta.securityRequirements.length > 0) {
+    return methodMeta.securityRequirements.map(requirement => ({
+      ...requirement
+    }));
+  }
+  if (!methodMeta?.security || methodMeta.security.length === 0) {
+    return undefined;
+  }
+  return methodMeta.security.map(scheme => ({
+    [scheme]: []
+  }));
+}
+function hasBearerAuthRequirement(security) {
+  return Boolean(security?.some(requirement => Object.keys(requirement).includes('bearerAuth')));
+}
+function createOperationObject(descriptor, methodMeta, responses, componentSchemas, security, context) {
+  const parameters = mergeOperationParameters(createParameters(descriptor.route.request, context), methodMeta?.parameters);
+  const requestBody = mergeOperationRequestBody(createRequestBody(descriptor.route.request, componentSchemas, context), methodMeta);
+  return {
+    operationId: normalizeOperationId(descriptor),
+    responses,
+    tags: resolveControllerTags(descriptor),
+    ...(methodMeta?.operation?.summary !== undefined && {
+      summary: methodMeta.operation.summary
+    }),
+    ...(methodMeta?.operation?.description !== undefined && {
+      description: methodMeta.operation.description
+    }),
+    ...(methodMeta?.operation?.deprecated !== undefined && {
+      deprecated: methodMeta.operation.deprecated
+    }),
+    ...(parameters.length > 0 && {
+      parameters
+    }),
+    ...(requestBody !== undefined && {
+      requestBody
+    }),
+    ...(security !== undefined && {
+      security
+    })
+  };
+}
+function buildOperationEntry(descriptor, componentSchemas, defaultErrorResponsesPolicy, context) {
+  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 responses = createOperationResponses(descriptor, methodMeta, componentSchemas, defaultErrorResponsesPolicy, context);
+  const security = createOperationSecurity(methodMeta);
+  const operation = createOperationObject(descriptor, methodMeta, responses, componentSchemas, security, context);
+  return {
+    method,
+    openApiPath,
+    operation,
+    requiresBearerAuth: hasBearerAuthRequirement(security)
+  };
+}
+function createOpenApiComponents(componentSchemas, hasBearerAuth, configuredSecuritySchemes) {
+  const securitySchemes = {
+    ...(configuredSecuritySchemes ?? {}),
+    ...(hasBearerAuth && !(configuredSecuritySchemes && 'bearerAuth' in configuredSecuritySchemes) ? {
+      bearerAuth: {
+        bearerFormat: 'JWT',
+        scheme: 'bearer',
+        type: 'http'
+      }
+    } : {})
+  };
+  return {
+    ...(Object.keys(componentSchemas).length > 0 && {
+      schemas: componentSchemas
+    }),
+    ...(Object.keys(securitySchemes).length > 0 && {
+      securitySchemes
+    })
+  };
+}
+function registerExtraModels(extraModels, componentSchemas, context) {
+  for (const model of extraModels ?? []) {
+    ensureComponentSchema(model, componentSchemas, context);
+  }
+}
+
+/**
+ * Build an OpenAPI 3.1.0 document directly from handler descriptors.
+ *
+ * @param options Document-generation input including handlers, metadata, and optional schema transforms.
+ * @returns A generated OpenAPI document ready to serialize or serve.
+ */
+/**
+ * Build an OpenAPI 3.1 document from discovered Fluo HTTP handler descriptors.
+ *
+ * @param options Document assembly options, descriptors, and optional schema transforms.
+ * @returns A fully normalized OpenAPI document ready to serve or snapshot in tests.
+ *
+ * @example
+ * ```ts
+ * const document = buildOpenApiDocument({
+ *   descriptors,
+ *   title: 'Public API',
+ *   version: '1.0.0',
+ * });
+ * ```
+ */
+export function buildOpenApiDocument(options) {
+  const paths = {};
+  const componentSchemas = {};
+  const defaultErrorResponsesPolicy = options.defaultErrorResponsesPolicy ?? 'inject';
+  const context = {
+    dtoEntries: new WeakMap(),
+    dtoSchemaNames: new WeakMap(),
+    usedSchemaNames: new Set(defaultErrorResponsesPolicy === 'inject' ? ['ErrorResponse'] : [])
+  };
+  let hasBearerAuth = false;
+  registerExtraModels(options.extraModels, componentSchemas, context);
+  for (const descriptor of options.descriptors) {
+    const entry = buildOperationEntry(descriptor, componentSchemas, defaultErrorResponsesPolicy, context);
+    if (!entry) {
+      continue;
+    }
+    const {
+      method,
+      openApiPath,
+      operation,
+      requiresBearerAuth
+    } = entry;
+    if (requiresBearerAuth) {
+      hasBearerAuth = true;
+    }
+    const pathItem = paths[openApiPath] ?? {};
+    pathItem[method] = operation;
+    paths[openApiPath] = pathItem;
+  }
+  const components = createOpenApiComponents(componentSchemas, hasBearerAuth, options.securitySchemes);
+  const document = {
+    ...(Object.keys(components).length > 0 && {
+      components
+    }),
+    info: {
+      title: options.title,
+      version: options.version
+    },
+    openapi: '3.1.0',
+    paths
+  };
+  return options.documentTransform ? options.documentTransform(document) : document;
+}