radiant-docs 0.1.58 → 0.1.60

package/template/src/lib/openapi/operation-doc.ts

@@ -0,0 +1,1150 @@
+import type { HttpMethods } from "oas/types";
+import type { OpenApiRoute } from "../routes";
+import { getOasInstance } from "../oas";
+import { loadOpenApiSpec } from "../validation";
+
+export const OPENAPI_REQUEST_SECTION_KEYS = [
+  "header",
+  "cookie",
+  "path",
+  "query",
+  "body",
+] as const;
+
+export type OpenApiRequestSectionKey =
+  (typeof OPENAPI_REQUEST_SECTION_KEYS)[number];
+
+export const OPENAPI_REQUEST_SECTION_LABELS: Record<
+  OpenApiRequestSectionKey,
+  string
+> = {
+  header: "Header",
+  cookie: "Cookie",
+  path: "Path Parameters",
+  query: "Query Parameters",
+  body: "Body",
+};
+
+export interface OpenApiFieldVariant {
+  label: string;
+  fields: OpenApiField[];
+}
+
+export interface OpenApiField {
+  name: string;
+  required: boolean;
+  type: string;
+  description: string;
+  enum?: (string | number)[];
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  hasDefault?: boolean;
+  defaultValue?: unknown;
+  isArray?: boolean;
+  style?: string;
+  explode?: boolean;
+  nested?: OpenApiField[];
+  variants?: OpenApiFieldVariant[];
+  variantType?: "oneOf" | "anyOf";
+  isAdditionalProperty?: boolean;
+  mapKnownKeys?: string[];
+}
+
+export type OpenApiRequestFields = Record<
+  OpenApiRequestSectionKey,
+  OpenApiField[]
+>;
+
+export interface OpenApiRequestSectionVariantData {
+  variants: OpenApiFieldVariant[];
+  variantType: "oneOf" | "anyOf";
+}
+
+export type OpenApiBodyDefaultKind = "object" | "array";
+
+export interface OpenApiOperationDoc {
+  api: any;
+  definition: any;
+  operation: any;
+  operationSpecSlice: any;
+  route: OpenApiRoute;
+  title: string;
+  description?: string;
+  method: string;
+  path: string;
+  responses: any;
+  serverUrl?: string;
+  requestFields: OpenApiRequestFields;
+  requestSectionVariants: Partial<
+    Record<OpenApiRequestSectionKey, OpenApiRequestSectionVariantData>
+  >;
+  bodyDescription: string;
+  bodyDefaultKind?: OpenApiBodyDefaultKind;
+}
+
+function createEmptyRequestFields(): OpenApiRequestFields {
+  return {
+    header: [],
+    cookie: [],
+    path: [],
+    query: [],
+    body: [],
+  };
+}
+
+function getSchemaVariants(schema: any): any[] {
+  if (!schema) return [];
+  if (Array.isArray(schema.oneOf)) return schema.oneOf;
+  if (Array.isArray(schema.anyOf)) return schema.anyOf;
+  return [];
+}
+
+function getSchemaVariantType(schema: any): "oneOf" | "anyOf" | undefined {
+  if (Array.isArray(schema?.oneOf) && schema.oneOf.length > 0) return "oneOf";
+  if (Array.isArray(schema?.anyOf) && schema.anyOf.length > 0) return "anyOf";
+  return undefined;
+}
+
+function getAdditionalPropertiesSchema(schema: any): any {
+  if (!schema || typeof schema !== "object") return undefined;
+
+  let additionalProperties = schema.additionalProperties;
+  if (Array.isArray(schema.allOf)) {
+    schema.allOf.forEach((part: any) => {
+      const partAdditional = getAdditionalPropertiesSchema(part);
+      if (partAdditional !== undefined) {
+        additionalProperties = partAdditional;
+      }
+    });
+  }
+
+  return additionalProperties;
+}
+
+function getSchemaEnumValues(schema: any): (string | number)[] | undefined {
+  if (!schema) return undefined;
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    const values = schema.enum.filter(
+      (value: unknown): value is string | number =>
+        typeof value === "string" || typeof value === "number",
+    );
+    return values.length > 0 ? values : undefined;
+  }
+
+  const variants = getSchemaVariants(schema);
+  if (variants.length === 0) return undefined;
+
+  const deduped = new Map<string, string | number>();
+  variants.forEach((variant) => {
+    const variantEnum = getSchemaEnumValues(variant);
+    variantEnum?.forEach((value) => {
+      deduped.set(`${typeof value}:${String(value)}`, value);
+    });
+  });
+
+  return deduped.size > 0 ? Array.from(deduped.values()) : undefined;
+}
+
+function parseFiniteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function parseNonNegativeInteger(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  if (!Number.isInteger(value) || value < 0) return undefined;
+  return value;
+}
+
+function getDirectSchemaNumericConstraints(schema: any): {
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+} {
+  const minimum = parseFiniteNumber(schema?.minimum);
+  const maximum = parseFiniteNumber(schema?.maximum);
+  const exclusiveMinimumValue = parseFiniteNumber(schema?.exclusiveMinimum);
+  const exclusiveMaximumValue = parseFiniteNumber(schema?.exclusiveMaximum);
+
+  const exclusiveMinimum =
+    exclusiveMinimumValue !== undefined
+      ? exclusiveMinimumValue
+      : schema?.exclusiveMinimum === true
+        ? minimum
+        : undefined;
+  const exclusiveMaximum =
+    exclusiveMaximumValue !== undefined
+      ? exclusiveMaximumValue
+      : schema?.exclusiveMaximum === true
+        ? maximum
+        : undefined;
+
+  const constraints: {
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+  } = {};
+
+  if (exclusiveMinimum !== undefined) {
+    constraints.exclusiveMinimum = exclusiveMinimum;
+  } else if (minimum !== undefined) {
+    constraints.minimum = minimum;
+  }
+
+  if (exclusiveMaximum !== undefined) {
+    constraints.exclusiveMaximum = exclusiveMaximum;
+  } else if (maximum !== undefined) {
+    constraints.maximum = maximum;
+  }
+
+  return constraints;
+}
+
+function mergeConjunctiveNumericConstraints(
+  base: {
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+  },
+  next: {
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+  },
+): {
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+} {
+  const toLowerBound = (constraint: typeof base) => {
+    if (constraint.exclusiveMinimum !== undefined) {
+      return { value: constraint.exclusiveMinimum, exclusive: true };
+    }
+    if (constraint.minimum !== undefined) {
+      return { value: constraint.minimum, exclusive: false };
+    }
+    return undefined;
+  };
+  const toUpperBound = (constraint: typeof base) => {
+    if (constraint.exclusiveMaximum !== undefined) {
+      return { value: constraint.exclusiveMaximum, exclusive: true };
+    }
+    if (constraint.maximum !== undefined) {
+      return { value: constraint.maximum, exclusive: false };
+    }
+    return undefined;
+  };
+
+  const pickStricterLower = (
+    first?: { value: number; exclusive: boolean },
+    second?: { value: number; exclusive: boolean },
+  ) => {
+    if (!first) return second;
+    if (!second) return first;
+    if (first.value > second.value) return first;
+    if (second.value > first.value) return second;
+    return {
+      value: first.value,
+      exclusive: first.exclusive || second.exclusive,
+    };
+  };
+  const pickStricterUpper = (
+    first?: { value: number; exclusive: boolean },
+    second?: { value: number; exclusive: boolean },
+  ) => {
+    if (!first) return second;
+    if (!second) return first;
+    if (first.value < second.value) return first;
+    if (second.value < first.value) return second;
+    return {
+      value: first.value,
+      exclusive: first.exclusive || second.exclusive,
+    };
+  };
+
+  const lower = pickStricterLower(toLowerBound(base), toLowerBound(next));
+  const upper = pickStricterUpper(toUpperBound(base), toUpperBound(next));
+
+  const merged: {
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+  } = {};
+  if (lower) {
+    if (lower.exclusive) merged.exclusiveMinimum = lower.value;
+    else merged.minimum = lower.value;
+  }
+  if (upper) {
+    if (upper.exclusive) merged.exclusiveMaximum = upper.value;
+    else merged.maximum = upper.value;
+  }
+
+  return merged;
+}
+
+function getSchemaNumericConstraints(
+  schema: any,
+  seen = new Set<any>(),
+): {
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+} {
+  if (!schema || typeof schema !== "object") return {};
+  if (seen.has(schema)) return {};
+
+  const nextSeen = new Set(seen);
+  nextSeen.add(schema);
+
+  let constraints = getDirectSchemaNumericConstraints(schema);
+
+  if (Array.isArray(schema.allOf)) {
+    schema.allOf.forEach((part: any) => {
+      constraints = mergeConjunctiveNumericConstraints(
+        constraints,
+        getSchemaNumericConstraints(part, nextSeen),
+      );
+    });
+  }
+
+  const variants = getSchemaVariants(schema);
+  if (variants.length > 0) {
+    const variantConstraints = variants.map((variant) =>
+      getSchemaNumericConstraints(variant, nextSeen),
+    );
+    const shared: {
+      minimum?: number;
+      maximum?: number;
+      exclusiveMinimum?: number;
+      exclusiveMaximum?: number;
+    } = {};
+    const keys = [
+      "minimum",
+      "maximum",
+      "exclusiveMinimum",
+      "exclusiveMaximum",
+    ] as const;
+
+    keys.forEach((key) => {
+      const firstValue = variantConstraints[0]?.[key];
+      if (firstValue === undefined) return;
+      const allMatch = variantConstraints.every(
+        (variantConstraint) => variantConstraint[key] === firstValue,
+      );
+      if (allMatch) {
+        shared[key] = firstValue;
+      }
+    });
+
+    constraints = mergeConjunctiveNumericConstraints(constraints, shared);
+  }
+
+  return constraints;
+}
+
+function getDirectSchemaStringLengthConstraints(schema: any): {
+  minLength?: number;
+  maxLength?: number;
+} {
+  const minLength = parseNonNegativeInteger(schema?.minLength);
+  const maxLength = parseNonNegativeInteger(schema?.maxLength);
+
+  const constraints: {
+    minLength?: number;
+    maxLength?: number;
+  } = {};
+  if (minLength !== undefined) constraints.minLength = minLength;
+  if (maxLength !== undefined) constraints.maxLength = maxLength;
+
+  return constraints;
+}
+
+function mergeConjunctiveStringLengthConstraints(
+  base: {
+    minLength?: number;
+    maxLength?: number;
+  },
+  next: {
+    minLength?: number;
+    maxLength?: number;
+  },
+): {
+  minLength?: number;
+  maxLength?: number;
+} {
+  const merged: {
+    minLength?: number;
+    maxLength?: number;
+  } = {};
+
+  const minLengthCandidates = [base.minLength, next.minLength].filter(
+    (value): value is number => value !== undefined,
+  );
+  const maxLengthCandidates = [base.maxLength, next.maxLength].filter(
+    (value): value is number => value !== undefined,
+  );
+
+  if (minLengthCandidates.length > 0) {
+    merged.minLength = Math.max(...minLengthCandidates);
+  }
+  if (maxLengthCandidates.length > 0) {
+    merged.maxLength = Math.min(...maxLengthCandidates);
+  }
+
+  return merged;
+}
+
+function getSchemaStringLengthConstraints(
+  schema: any,
+  seen = new Set<any>(),
+): {
+  minLength?: number;
+  maxLength?: number;
+} {
+  if (!schema || typeof schema !== "object") return {};
+  if (seen.has(schema)) return {};
+
+  const nextSeen = new Set(seen);
+  nextSeen.add(schema);
+
+  let constraints = getDirectSchemaStringLengthConstraints(schema);
+
+  if (Array.isArray(schema.allOf)) {
+    schema.allOf.forEach((part: any) => {
+      constraints = mergeConjunctiveStringLengthConstraints(
+        constraints,
+        getSchemaStringLengthConstraints(part, nextSeen),
+      );
+    });
+  }
+
+  const variants = getSchemaVariants(schema);
+  if (variants.length > 0) {
+    const variantConstraints = variants.map((variant) =>
+      getSchemaStringLengthConstraints(variant, nextSeen),
+    );
+    const shared: {
+      minLength?: number;
+      maxLength?: number;
+    } = {};
+
+    (["minLength", "maxLength"] as const).forEach((key) => {
+      const firstValue = variantConstraints[0]?.[key];
+      if (firstValue === undefined) return;
+      const allMatch = variantConstraints.every(
+        (variantConstraint) => variantConstraint[key] === firstValue,
+      );
+      if (allMatch) {
+        shared[key] = firstValue;
+      }
+    });
+
+    constraints = mergeConjunctiveStringLengthConstraints(constraints, shared);
+  }
+
+  return constraints;
+}
+
+function getSchemaTypeLabel(schema: any): string {
+  if (!schema) return "unknown";
+
+  const variants = getSchemaVariants(schema);
+  if (variants.length > 0) {
+    const labels = Array.from(
+      new Set(
+        variants
+          .map((variant) => getSchemaTypeLabel(variant))
+          .filter((label) => label.length > 0),
+      ),
+    );
+    if (labels.length === 0) return "unknown";
+    return labels.length === 1 ? labels[0] : labels.join(" | ");
+  }
+
+  if (schema.type === "array") {
+    const itemSchema = schema.items;
+    if (!itemSchema) return "unknown[]";
+    const itemType = getSchemaTypeLabel(itemSchema);
+    if (itemType.includes(" | ")) return `(${itemType})[]`;
+    return `${itemType}[]`;
+  }
+
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    return `enum<${schema.type || "string"}>`;
+  }
+
+  if (schema.format && schema.type) {
+    return `${schema.type} (${schema.format})`;
+  }
+
+  if (schema.type) return schema.type;
+  if (schema.properties || schema.allOf || schema.oneOf || schema.anyOf) {
+    return "object";
+  }
+  return "unknown";
+}
+
+function getSchemaStructuralType(
+  schema: any,
+): OpenApiBodyDefaultKind | undefined {
+  if (!schema || typeof schema !== "object") return undefined;
+
+  if (schema.type === "object") return "object";
+  if (schema.type === "array") return "array";
+
+  const variants = getSchemaVariants(schema);
+  if (variants.length > 0) {
+    const variantTypes = Array.from(
+      new Set(
+        variants
+          .map((variant) => getSchemaStructuralType(variant))
+          .filter(
+            (variantType): variantType is OpenApiBodyDefaultKind =>
+              variantType === "object" || variantType === "array",
+          ),
+      ),
+    );
+    if (variantTypes.length === 1) return variantTypes[0];
+    return undefined;
+  }
+
+  if (
+    (schema.properties && typeof schema.properties === "object") ||
+    schema.additionalProperties !== undefined
+  ) {
+    return "object";
+  }
+
+  if (schema.items) return "array";
+
+  if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+    const allOfTypes = Array.from(
+      new Set(
+        schema.allOf
+          .map((part: any) => getSchemaStructuralType(part))
+          .filter(
+            (partType): partType is OpenApiBodyDefaultKind =>
+              partType === "object" || partType === "array",
+          ),
+      ),
+    );
+    if (allOfTypes.length === 1) return allOfTypes[0];
+  }
+
+  return undefined;
+}
+
+function getTopLevelObjectShape(schema: any): {
+  properties: Record<string, any>;
+  required: Set<string>;
+  hasObjectShape: boolean;
+} {
+  if (!schema) {
+    return {
+      properties: {},
+      required: new Set<string>(),
+      hasObjectShape: false,
+    };
+  }
+
+  let properties: Record<string, any> = {};
+  const required = new Set<string>(
+    Array.isArray(schema.required) ? schema.required : [],
+  );
+  let hasObjectShape = false;
+
+  if (schema.properties && typeof schema.properties === "object") {
+    properties = { ...properties, ...schema.properties };
+    hasObjectShape = true;
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    schema.allOf.forEach((part: any) => {
+      const partShape = getTopLevelObjectShape(part);
+      if (!partShape.hasObjectShape) return;
+
+      properties = { ...properties, ...partShape.properties };
+      partShape.required.forEach((name) => required.add(name));
+      hasObjectShape = true;
+    });
+  }
+
+  const variants = getSchemaVariants(schema);
+  if (variants.length > 0) {
+    const variantShapes = variants
+      .map((variant) => getTopLevelObjectShape(variant))
+      .filter((shape) => shape.hasObjectShape);
+
+    if (variantShapes.length > 0) {
+      variantShapes.forEach((shape) => {
+        properties = { ...properties, ...shape.properties };
+      });
+
+      const [firstShape, ...restShapes] = variantShapes;
+      const requiredAcrossVariants = new Set<string>(firstShape.required);
+      restShapes.forEach((shape) => {
+        Array.from(requiredAcrossVariants).forEach((name) => {
+          if (!shape.required.has(name)) {
+            requiredAcrossVariants.delete(name);
+          }
+        });
+      });
+      requiredAcrossVariants.forEach((name) => required.add(name));
+      hasObjectShape = true;
+    }
+  }
+
+  return { properties, required, hasObjectShape };
+}
+
+function extractRequestSchemaContent(
+  schema: any,
+  seen = new Set<any>(),
+): {
+  fields: OpenApiField[];
+  variants?: OpenApiFieldVariant[];
+  variantType?: "oneOf" | "anyOf";
+} {
+  if (!schema || typeof schema !== "object") return { fields: [] };
+  if (seen.has(schema)) return { fields: [] };
+
+  const nextSeen = new Set(seen);
+  nextSeen.add(schema);
+
+  if (schema.type === "array" && schema.items) {
+    return extractRequestSchemaContent(schema.items, nextSeen);
+  }
+
+  const baseSchema = { ...schema };
+  delete baseSchema.oneOf;
+  delete baseSchema.anyOf;
+
+  const shape = getTopLevelObjectShape(baseSchema);
+
+  const fields: OpenApiField[] = Object.entries(shape.properties)
+    .sort(([nameA], [nameB]) => {
+      const aRequired = shape.required.has(nameA);
+      const bRequired = shape.required.has(nameB);
+      if (aRequired && !bRequired) return -1;
+      if (!aRequired && bRequired) return 1;
+      return 0;
+    })
+    .map(([name, propertySchema]: [string, any]) => {
+      const nestedContent = extractRequestSchemaContent(
+        propertySchema,
+        nextSeen,
+      );
+      return {
+        name,
+        required: shape.required.has(name),
+        type: getSchemaTypeLabel(propertySchema),
+        description: propertySchema?.description || "",
+        enum: getSchemaEnumValues(propertySchema),
+        ...getSchemaStringLengthConstraints(propertySchema, nextSeen),
+        ...getSchemaNumericConstraints(propertySchema, nextSeen),
+        hasDefault: Object.prototype.hasOwnProperty.call(
+          propertySchema || {},
+          "default",
+        ),
+        defaultValue: propertySchema?.default,
+        isArray: propertySchema?.type === "array",
+        nested:
+          nestedContent.fields.length > 0 ? nestedContent.fields : undefined,
+        variants: nestedContent.variants,
+        variantType: nestedContent.variantType,
+      };
+    });
+
+  const additionalProperties = getAdditionalPropertiesSchema(baseSchema);
+  const supportsAdditionalProperties =
+    additionalProperties === true ||
+    (additionalProperties &&
+      typeof additionalProperties === "object" &&
+      !Array.isArray(additionalProperties));
+
+  if (supportsAdditionalProperties) {
+    const additionalSchema =
+      additionalProperties && typeof additionalProperties === "object"
+        ? additionalProperties
+        : null;
+    const additionalContent = additionalSchema
+      ? extractRequestSchemaContent(additionalSchema, nextSeen)
+      : { fields: [] as OpenApiField[] };
+
+    fields.push({
+      name: "[key: string]",
+      required: false,
+      type: additionalSchema ? getSchemaTypeLabel(additionalSchema) : "any",
+      description: additionalSchema?.description || "",
+      enum: additionalSchema
+        ? getSchemaEnumValues(additionalSchema)
+        : undefined,
+      ...getSchemaStringLengthConstraints(additionalSchema, nextSeen),
+      ...getSchemaNumericConstraints(additionalSchema, nextSeen),
+      hasDefault: Object.prototype.hasOwnProperty.call(
+        additionalSchema || {},
+        "default",
+      ),
+      defaultValue: additionalSchema?.default,
+      isArray: additionalSchema?.type === "array",
+      nested:
+        additionalContent.fields.length > 0
+          ? additionalContent.fields
+          : undefined,
+      variants: additionalContent.variants,
+      variantType: additionalContent.variantType,
+      isAdditionalProperty: true,
+      mapKnownKeys: Object.keys(shape.properties),
+    });
+  }
+
+  const variantType = getSchemaVariantType(schema);
+  const variantSchemas =
+    variantType === "oneOf"
+      ? schema.oneOf || []
+      : variantType === "anyOf"
+        ? schema.anyOf || []
+        : [];
+  const variants =
+    variantType && variantSchemas.length > 0
+      ? variantSchemas
+          .map((variantSchema: any, index: number) => ({
+            label: `Variant ${index + 1}`,
+            fields: extractRequestSchemaContent(variantSchema, nextSeen).fields,
+          }))
+          .filter((variant: OpenApiFieldVariant) => variant.fields.length > 0)
+      : [];
+
+  return {
+    fields,
+    variants: variants.length > 0 ? variants : undefined,
+    variantType: variants.length > 0 ? variantType : undefined,
+  };
+}
+
+function addSecurityFields(args: {
+  operation: any;
+  definition: any;
+  requestFields: OpenApiRequestFields;
+}) {
+  const securityRequirements = args.operation.getSecurity();
+  const schemes = args.definition.components?.securitySchemes || {};
+
+  if (!securityRequirements || securityRequirements.length === 0) return;
+
+  const firstOption = securityRequirements[0];
+
+  Object.keys(firstOption).forEach((key) => {
+    const scheme = schemes[key];
+    if (!scheme) return;
+
+    const fieldData: OpenApiField = {
+      name: "",
+      required: true,
+      type: "string",
+      description: scheme.description || "",
+    };
+
+    if (scheme.type === "apiKey") {
+      fieldData.name = scheme.name;
+
+      if (!fieldData.description) {
+        fieldData.description = `API Key required in ${scheme.in}.`;
+      }
+
+      if (scheme.in === "header") args.requestFields.header.push(fieldData);
+      else if (scheme.in === "query") args.requestFields.query.push(fieldData);
+      else if (scheme.in === "cookie") {
+        args.requestFields.cookie.push(fieldData);
+      }
+    } else if (scheme.type === "http") {
+      fieldData.name = "Authorization";
+
+      if (scheme.scheme === "bearer") {
+        fieldData.description =
+          fieldData.description || "Bearer token authentication.";
+      } else if (scheme.scheme === "basic") {
+        fieldData.description =
+          fieldData.description ||
+          "Basic authentication (Base64 encoded username:password).";
+      }
+
+      args.requestFields.header.push(fieldData);
+    } else if (scheme.type === "oauth2" || scheme.type === "openIdConnect") {
+      fieldData.name = "Authorization";
+      fieldData.description = fieldData.description || "OAuth2 Bearer Token.";
+
+      args.requestFields.header.push(fieldData);
+    }
+  });
+}
+
+function buildOpenApiRequestModel(args: {
+  operation: any;
+  definition: any;
+}): {
+  requestFields: OpenApiRequestFields;
+  requestSectionVariants: Partial<
+    Record<OpenApiRequestSectionKey, OpenApiRequestSectionVariantData>
+  >;
+  bodyDescription: string;
+  bodyDefaultKind?: OpenApiBodyDefaultKind;
+} {
+  const requestFields = createEmptyRequestFields();
+  const requestSectionVariants: Partial<
+    Record<OpenApiRequestSectionKey, OpenApiRequestSectionVariantData>
+  > = {};
+  let bodyDescription = "";
+  let bodyDefaultKind: OpenApiBodyDefaultKind | undefined = undefined;
+
+  addSecurityFields({
+    operation: args.operation,
+    definition: args.definition,
+    requestFields,
+  });
+
+  const parameters = args.operation.getParameters();
+  parameters.forEach((param: any) => {
+    const schema = param.schema as any;
+    const isArray = schema?.type === "array";
+    const schemaContent = extractRequestSchemaContent(schema);
+
+    const field: OpenApiField = {
+      name: param.name,
+      required: param.required || false,
+      type: getSchemaTypeLabel(schema),
+      description: param.description || "",
+      enum: getSchemaEnumValues(schema),
+      ...getSchemaStringLengthConstraints(schema),
+      ...getSchemaNumericConstraints(schema),
+      hasDefault: Object.prototype.hasOwnProperty.call(schema || {}, "default"),
+      defaultValue: schema?.default,
+      isArray,
+      style: param.style,
+      explode: param.explode,
+      nested: schemaContent.fields.length > 0 ? schemaContent.fields : undefined,
+      variants: schemaContent.variants,
+      variantType: schemaContent.variantType,
+    };
+
+    if (param.in === "path") requestFields.path.push(field);
+    if (param.in === "query") requestFields.query.push(field);
+    if (param.in === "header") requestFields.header.push(field);
+    if (param.in === "cookie") requestFields.cookie.push(field);
+  });
+
+  if (args.operation.hasRequestBody()) {
+    const requestBody = args.operation.getRequestBody("application/json");
+    const requestBodyObject = args.operation.schema.requestBody;
+    const bodySchema = (requestBody as any)?.schema as any;
+    bodyDescription =
+      requestBodyObject?.description ||
+      (requestBody as any)?.description ||
+      bodySchema?.description ||
+      "";
+    bodyDefaultKind = getSchemaStructuralType(bodySchema);
+    const bodyContent = extractRequestSchemaContent(bodySchema);
+    requestFields.body.push(...bodyContent.fields);
+
+    if (bodyContent.variants && bodyContent.variantType) {
+      requestSectionVariants.body = {
+        variants: bodyContent.variants,
+        variantType: bodyContent.variantType,
+      };
+    }
+  }
+
+  return {
+    requestFields,
+    requestSectionVariants,
+    bodyDescription,
+    bodyDefaultKind,
+  };
+}
+
+function cloneJson<T>(value: T): T {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function decodeJsonPointerSegment(segment: string): string {
+  return decodeURIComponent(segment).replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function getJsonPointerSegments(ref: string): string[] | null {
+  if (!ref.startsWith("#/")) return null;
+
+  return ref.slice(2).split("/").map(decodeJsonPointerSegment);
+}
+
+function getByJsonPointer(source: any, ref: string): unknown {
+  const segments = getJsonPointerSegments(ref);
+  if (!segments) return undefined;
+
+  let current = source;
+  for (const segment of segments) {
+    if (!current || typeof current !== "object") return undefined;
+    current = current[segment];
+  }
+
+  return current;
+}
+
+function setByJsonPointer(target: any, ref: string, value: unknown) {
+  const segments = getJsonPointerSegments(ref);
+  if (!segments || segments.length === 0) return;
+
+  let current = target;
+  segments.slice(0, -1).forEach((segment) => {
+    if (
+      !Object.prototype.hasOwnProperty.call(current, segment) ||
+      !current[segment] ||
+      typeof current[segment] !== "object" ||
+      Array.isArray(current[segment])
+    ) {
+      current[segment] = {};
+    }
+    current = current[segment];
+  });
+
+  current[segments[segments.length - 1]] = cloneJson(value);
+}
+
+function collectLocalRefs(args: {
+  value: unknown;
+  source: any;
+  target: any;
+  seenRefs: Set<string>;
+}) {
+  if (Array.isArray(args.value)) {
+    args.value.forEach((item) =>
+      collectLocalRefs({
+        value: item,
+        source: args.source,
+        target: args.target,
+        seenRefs: args.seenRefs,
+      }),
+    );
+    return;
+  }
+
+  if (!args.value || typeof args.value !== "object") return;
+
+  const ref = (args.value as { $ref?: unknown }).$ref;
+  if (typeof ref === "string" && ref.startsWith("#/")) {
+    if (!args.seenRefs.has(ref)) {
+      args.seenRefs.add(ref);
+      const targetValue = getByJsonPointer(args.source, ref);
+
+      if (targetValue !== undefined) {
+        setByJsonPointer(args.target, ref, targetValue);
+        collectLocalRefs({
+          value: targetValue,
+          source: args.source,
+          target: args.target,
+          seenRefs: args.seenRefs,
+        });
+      }
+    }
+  }
+
+  Object.values(args.value).forEach((child) =>
+    collectLocalRefs({
+      value: child,
+      source: args.source,
+      target: args.target,
+      seenRefs: args.seenRefs,
+    }),
+  );
+}
+
+function getPathItemForOperation(args: {
+  spec: any;
+  path: string;
+}): { pathKey: string; pathItem: any } | null {
+  const paths = args.spec?.paths;
+  if (!paths || typeof paths !== "object") return null;
+
+  const targetPath = args.path.toLowerCase();
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    if (pathKey.toLowerCase() !== targetPath) continue;
+    if (!pathItem || typeof pathItem !== "object") return null;
+
+    return { pathKey, pathItem };
+  }
+
+  return null;
+}
+
+function getSecurityRequirementForSlice(args: {
+  spec: any;
+  operation: any;
+}): unknown {
+  if (Object.prototype.hasOwnProperty.call(args.operation, "security")) {
+    return args.operation.security;
+  }
+
+  return args.spec?.security;
+}
+
+function collectSecuritySchemes(args: {
+  source: any;
+  target: any;
+  securityRequirements: unknown;
+}) {
+  if (!Array.isArray(args.securityRequirements)) return;
+
+  args.securityRequirements.forEach((requirement) => {
+    if (!requirement || typeof requirement !== "object") return;
+
+    Object.keys(requirement).forEach((schemeName) => {
+      const scheme = args.source?.components?.securitySchemes?.[schemeName];
+      if (!scheme) return;
+
+      args.target.components ??= {};
+      args.target.components.securitySchemes ??= {};
+      args.target.components.securitySchemes[schemeName] = cloneJson(scheme);
+    });
+  });
+}
+
+function addRelevantTags(args: {
+  source: any;
+  target: any;
+  operation: any;
+}) {
+  if (
+    !args.operation ||
+    !Array.isArray(args.source?.tags) ||
+    !Array.isArray(args.operation.tags)
+  ) {
+    return;
+  }
+
+  const operationTagNames = new Set(args.operation.tags);
+  const tags = args.source.tags.filter(
+    (tag: any) => tag?.name && operationTagNames.has(tag.name),
+  );
+
+  if (tags.length > 0) {
+    args.target.tags = cloneJson(tags);
+  }
+}
+
+export function buildOpenApiOperationSpecSlice(args: {
+  spec: any;
+  path: string;
+  method: string;
+}): any {
+  const method = args.method.toLowerCase();
+  const pathMatch = getPathItemForOperation({
+    spec: args.spec,
+    path: args.path,
+  });
+  const pathKey = pathMatch?.pathKey ?? args.path;
+  const pathItem = pathMatch?.pathItem ?? {};
+  const operation = pathItem[method];
+
+  const slicedPathItem: Record<string, unknown> = {};
+  if (pathItem.parameters) {
+    slicedPathItem.parameters = cloneJson(pathItem.parameters);
+  }
+  if (pathItem.servers) {
+    slicedPathItem.servers = cloneJson(pathItem.servers);
+  }
+  if (operation) {
+    slicedPathItem[method] = cloneJson(operation);
+  }
+
+  const slice: Record<string, unknown> = {
+    ...(args.spec.openapi ? { openapi: args.spec.openapi } : {}),
+    ...(args.spec.swagger ? { swagger: args.spec.swagger } : {}),
+    ...(args.spec.info ? { info: cloneJson(args.spec.info) } : {}),
+    ...(args.spec.servers ? { servers: cloneJson(args.spec.servers) } : {}),
+    paths: {
+      [pathKey]: slicedPathItem,
+    },
+  };
+
+  const securityRequirements = operation
+    ? getSecurityRequirementForSlice({
+        spec: args.spec,
+        operation,
+      })
+    : undefined;
+
+  if (
+    securityRequirements !== undefined &&
+    !Object.prototype.hasOwnProperty.call(operation || {}, "security")
+  ) {
+    slice.security = cloneJson(securityRequirements);
+  }
+
+  addRelevantTags({
+    source: args.spec,
+    target: slice,
+    operation,
+  });
+  collectSecuritySchemes({
+    source: args.spec,
+    target: slice,
+    securityRequirements,
+  });
+  collectLocalRefs({
+    value: slice.paths,
+    source: args.spec,
+    target: slice,
+    seenRefs: new Set<string>(),
+  });
+
+  return slice;
+}
+
+export async function getOpenApiOperationDoc(
+  route: OpenApiRoute,
+): Promise<OpenApiOperationDoc> {
+  const [api, spec] = await Promise.all([
+    getOasInstance(route.filePath),
+    loadOpenApiSpec(route.filePath),
+  ]);
+  const definition = api.getDefinition();
+  const operation = api.operation(
+    route.openApiPath,
+    route.openApiMethod as HttpMethods,
+  );
+  const requestModel = buildOpenApiRequestModel({
+    operation,
+    definition,
+  });
+
+  return {
+    api,
+    definition,
+    operation,
+    operationSpecSlice: buildOpenApiOperationSpecSlice({
+      spec,
+      path: route.openApiPath,
+      method: route.openApiMethod,
+    }),
+    route,
+    title: route.title,
+    description: operation.getDescription() || undefined,
+    method: route.openApiMethod,
+    path: route.openApiPath,
+    responses: operation.schema.responses,
+    serverUrl: definition.servers?.[0]?.url,
+    ...requestModel,
+  };
+}