radiant-docs 0.1.64 → 0.1.65

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

@@ -2,6 +2,7 @@ import type { HttpMethods } from "oas/types";
 import type { OpenApiRoute } from "../routes";
 import { getOasInstance } from "../oas";
 import { loadOpenApiSpec } from "../validation";
+import { getSchemaVariantLabel } from "./schema-variant-labels";
 
 export const OPENAPI_REQUEST_SECTION_KEYS = [
   "header",
@@ -30,6 +31,11 @@ export interface OpenApiFieldVariant {
   fields: OpenApiField[];
 }
 
+export interface OpenApiFieldValueVariant {
+  label: string;
+  field: OpenApiField;
+}
+
 export interface OpenApiField {
   name: string;
   required: boolean;
@@ -50,8 +56,13 @@ export interface OpenApiField {
   nested?: OpenApiField[];
   variants?: OpenApiFieldVariant[];
   variantType?: "oneOf" | "anyOf";
+  valueVariants?: OpenApiFieldValueVariant[];
+  valueVariantType?: "oneOf" | "anyOf";
   isAdditionalProperty?: boolean;
   mapKnownKeys?: string[];
+  renderAsJson?: boolean;
+  isFile?: boolean;
+  valuePrefix?: string;
 }
 
 export type OpenApiRequestFields = Record<
@@ -84,6 +95,7 @@ export interface OpenApiOperationDoc {
   >;
   bodyDescription: string;
   bodyDefaultKind?: OpenApiBodyDefaultKind;
+  requestBodyContentType?: string;
 }
 
 function createEmptyRequestFields(): OpenApiRequestFields {
@@ -109,6 +121,44 @@ function getSchemaVariantType(schema: any): "oneOf" | "anyOf" | undefined {
   return undefined;
 }
 
+function isNullSchema(schema: any): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  if (schema.type === "null") return true;
+  return Array.isArray(schema.type) && schema.type.includes("null");
+}
+
+function unwrapNullableSchema(schema: any, seen = new Set<any>()): any {
+  if (!schema || typeof schema !== "object") return schema;
+  if (seen.has(schema)) return schema;
+
+  const nextSeen = new Set(seen);
+  nextSeen.add(schema);
+
+  if (Array.isArray(schema.type) && schema.type.includes("null")) {
+    const nonNullTypes = schema.type.filter((type: string) => type !== "null");
+    if (nonNullTypes.length === 1) {
+      return unwrapNullableSchema(
+        {
+          ...schema,
+          type: nonNullTypes[0],
+        },
+        nextSeen,
+      );
+    }
+  }
+
+  const variantType = getSchemaVariantType(schema);
+  if (!variantType) return schema;
+
+  const variants = getSchemaVariants(schema);
+  const nonNullVariants = variants.filter((variant) => !isNullSchema(variant));
+  if (nonNullVariants.length === 1 && nonNullVariants.length < variants.length) {
+    return unwrapNullableSchema(nonNullVariants[0], nextSeen);
+  }
+
+  return schema;
+}
+
 function getAdditionalPropertiesSchema(schema: any): any {
   if (!schema || typeof schema !== "object") return undefined;
 
@@ -125,6 +175,60 @@ function getAdditionalPropertiesSchema(schema: any): any {
   return additionalProperties;
 }
 
+function isEmptySchema(schema: any): boolean {
+  return (
+    schema &&
+    typeof schema === "object" &&
+    !Array.isArray(schema) &&
+    Object.keys(schema).length === 0
+  );
+}
+
+function getSchemaDefault(schema: any, seen = new Set<any>()): {
+  hasDefault: boolean;
+  defaultValue?: unknown;
+} {
+  if (!schema || typeof schema !== "object") return { hasDefault: false };
+
+  if (Object.prototype.hasOwnProperty.call(schema, "default")) {
+    return { hasDefault: true, defaultValue: schema.default };
+  }
+
+  if (seen.has(schema)) return { hasDefault: false };
+
+  const nextSeen = new Set(seen);
+  nextSeen.add(schema);
+
+  const variantType = getSchemaVariantType(schema);
+  if (!variantType) return { hasDefault: false };
+
+  const variants = getSchemaVariants(schema);
+  const nonNullVariants = variants.filter((variant) => !isNullSchema(variant));
+  if (nonNullVariants.length === 1 && nonNullVariants.length < variants.length) {
+    return getSchemaDefault(nonNullVariants[0], nextSeen);
+  }
+
+  return { hasDefault: false };
+}
+
+function shouldRenderSchemaAsJson(schema: any): boolean {
+  const renderSchema = unwrapNullableSchema(schema);
+  if (!renderSchema || typeof renderSchema !== "object") return false;
+  if (getSchemaStructuralType(renderSchema) !== "object") return false;
+  if (getSchemaVariantType(renderSchema)) return false;
+
+  const shape = getTopLevelObjectShape(renderSchema);
+  if (Object.keys(shape.properties).length > 0) return false;
+
+  const additionalProperties = getAdditionalPropertiesSchema(renderSchema);
+  return additionalProperties === true || isEmptySchema(additionalProperties);
+}
+
+function isFileUploadSchema(schema: any): boolean {
+  const renderSchema = unwrapNullableSchema(schema);
+  return renderSchema?.type === "string" && renderSchema?.format === "binary";
+}
+
 function getSchemaEnumValues(schema: any): (string | number)[] | undefined {
   if (!schema) return undefined;
   if (Array.isArray(schema.enum) && schema.enum.length > 0) {
@@ -501,19 +605,33 @@ function getSchemaStructuralType(
 ): OpenApiBodyDefaultKind | undefined {
   if (!schema || typeof schema !== "object") return undefined;
 
+  const renderSchema = unwrapNullableSchema(schema);
+  if (renderSchema !== schema) return getSchemaStructuralType(renderSchema);
+
   if (schema.type === "object") return "object";
   if (schema.type === "array") return "array";
 
   const variants = getSchemaVariants(schema);
   if (variants.length > 0) {
+    const nonNullVariants = variants.filter((variant) => !isNullSchema(variant));
+    const structuralVariantTypes = nonNullVariants.map((variant) =>
+      getSchemaStructuralType(variant),
+    );
+    if (
+      structuralVariantTypes.some(
+        (variantType) =>
+          variantType !== "object" && variantType !== "array",
+      )
+    ) {
+      return undefined;
+    }
+
     const variantTypes = Array.from(
       new Set(
-        variants
-          .map((variant) => getSchemaStructuralType(variant))
-          .filter(
-            (variantType): variantType is OpenApiBodyDefaultKind =>
-              variantType === "object" || variantType === "array",
-          ),
+        structuralVariantTypes.filter(
+          (variantType): variantType is OpenApiBodyDefaultKind =>
+            variantType === "object" || variantType === "array",
+        ),
       ),
     );
     if (variantTypes.length === 1) return variantTypes[0];
@@ -609,6 +727,139 @@ function getTopLevelObjectShape(schema: any): {
   return { properties, required, hasObjectShape };
 }
 
+function getSchemaVariantObjectProperties(schema: any): Record<string, any> {
+  return getTopLevelObjectShape(schema).properties;
+}
+
+function getSchemaDescription(schema: any): string {
+  if (!schema || typeof schema !== "object") return "";
+  if (typeof schema.description === "string") return schema.description;
+
+  const renderSchema = unwrapNullableSchema(schema);
+  if (
+    renderSchema &&
+    renderSchema !== schema &&
+    typeof renderSchema.description === "string"
+  ) {
+    return renderSchema.description;
+  }
+
+  return "";
+}
+
+function getValueVariantData(
+  schema: any,
+): { variantType: "oneOf" | "anyOf"; schemas: any[] } | undefined {
+  const renderSchema = unwrapNullableSchema(schema);
+  const variantType = getSchemaVariantType(renderSchema);
+  if (!variantType) return undefined;
+
+  const variantSchemas = getSchemaVariants(renderSchema)
+    .filter((variant) => !isNullSchema(variant))
+    .map((variant) => unwrapNullableSchema(variant));
+
+  if (variantSchemas.length < 2) return undefined;
+
+  const variantShapeTypes = variantSchemas.map((variantSchema) => {
+    const structuralType = getSchemaStructuralType(variantSchema);
+    if (structuralType === "array" || structuralType === "object") {
+      return structuralType;
+    }
+    if (getTopLevelObjectShape(variantSchema).hasObjectShape) return "object";
+    return "scalar";
+  });
+
+  const hasArrayShape = variantShapeTypes.includes("array");
+  const hasObjectShape = variantShapeTypes.includes("object");
+  const hasScalarShape = variantShapeTypes.includes("scalar");
+  const hasValueShapeChoice =
+    hasArrayShape || (hasObjectShape && hasScalarShape);
+
+  if (!hasValueShapeChoice) return undefined;
+  return { variantType, schemas: variantSchemas };
+}
+
+function createOpenApiFieldFromSchema(args: {
+  name: string;
+  required: boolean;
+  schema: any;
+  seen: Set<any>;
+  description?: string;
+  style?: string;
+  explode?: boolean;
+  isAdditionalProperty?: boolean;
+  mapKnownKeys?: string[];
+  includeValueVariants?: boolean;
+}): OpenApiField {
+  const {
+    name,
+    required,
+    schema,
+    seen,
+    description,
+    style,
+    explode,
+    isAdditionalProperty,
+    mapKnownKeys,
+    includeValueVariants = true,
+  } = args;
+  const renderSchema = unwrapNullableSchema(schema);
+  const valueVariantData = includeValueVariants
+    ? getValueVariantData(renderSchema)
+    : undefined;
+  const nestedSchema = valueVariantData ? undefined : renderSchema;
+  const nestedContent = nestedSchema
+    ? extractRequestSchemaContent(nestedSchema, seen)
+    : { fields: [] as OpenApiField[] };
+  const schemaDefault = getSchemaDefault(schema);
+
+  const field: OpenApiField = {
+    name,
+    required,
+    type: getSchemaTypeLabel(schema),
+    description: description || getSchemaDescription(schema),
+    enum: getSchemaEnumValues(schema),
+    ...getSchemaStringLengthConstraints(schema, seen),
+    ...getSchemaNumericConstraints(schema, seen),
+    hasDefault: schemaDefault.hasDefault,
+    defaultValue: schemaDefault.defaultValue,
+    isArray: getSchemaStructuralType(renderSchema) === "array",
+    style,
+    explode,
+    nested: nestedContent.fields.length > 0 ? nestedContent.fields : undefined,
+    variants: nestedContent.variants,
+    variantType: nestedContent.variantType,
+    isAdditionalProperty,
+    mapKnownKeys,
+    renderAsJson: shouldRenderSchemaAsJson(renderSchema),
+    isFile: isFileUploadSchema(renderSchema),
+  };
+
+  if (valueVariantData) {
+    field.valueVariants = valueVariantData.schemas.map(
+      (variantSchema, index) => ({
+        label: getSchemaVariantLabel(variantSchema, index, {
+          parentSchema: renderSchema,
+          siblings: valueVariantData.schemas,
+          getObjectProperties: getSchemaVariantObjectProperties,
+          getTypeLabel: getSchemaTypeLabel,
+        }),
+        field: createOpenApiFieldFromSchema({
+          name,
+          required,
+          schema: variantSchema,
+          seen,
+          description: getSchemaDescription(variantSchema),
+          includeValueVariants: false,
+        }),
+      }),
+    );
+    field.valueVariantType = valueVariantData.variantType;
+  }
+
+  return field;
+}
+
 function extractRequestSchemaContent(
   schema: any,
   seen = new Set<any>(),
@@ -642,29 +893,12 @@ function extractRequestSchemaContent(
       return 0;
     })
     .map(([name, propertySchema]: [string, any]) => {
-      const nestedContent = extractRequestSchemaContent(
-        propertySchema,
-        nextSeen,
-      );
-      return {
+      return createOpenApiFieldFromSchema({
         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,
-      };
+        schema: propertySchema,
+        seen: nextSeen,
+      });
     });
 
   const additionalProperties = getAdditionalPropertiesSchema(baseSchema);
@@ -679,35 +913,16 @@ function extractRequestSchemaContent(
       additionalProperties && typeof additionalProperties === "object"
         ? additionalProperties
         : null;
-    const additionalContent = additionalSchema
-      ? extractRequestSchemaContent(additionalSchema, nextSeen)
-      : { fields: [] as OpenApiField[] };
 
-    fields.push({
+    fields.push(createOpenApiFieldFromSchema({
       name: "[key: string]",
       required: false,
-      type: additionalSchema ? getSchemaTypeLabel(additionalSchema) : "any",
+      schema: additionalSchema,
+      seen: nextSeen,
       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);
@@ -720,10 +935,28 @@ function extractRequestSchemaContent(
   const variants =
     variantType && variantSchemas.length > 0
       ? variantSchemas
-          .map((variantSchema: any, index: number) => ({
-            label: `Variant ${index + 1}`,
-            fields: extractRequestSchemaContent(variantSchema, nextSeen).fields,
-          }))
+          .flatMap((variantSchema: any, index: number) => {
+            const variantContent = extractRequestSchemaContent(
+              variantSchema,
+              nextSeen,
+            );
+
+            if (variantContent.fields.length > 0) {
+              return [
+                {
+                  label: getSchemaVariantLabel(variantSchema, index, {
+                    parentSchema: schema,
+                    siblings: variantSchemas,
+                    getObjectProperties: getSchemaVariantObjectProperties,
+                    getTypeLabel: getSchemaTypeLabel,
+                  }),
+                  fields: variantContent.fields,
+                },
+              ];
+            }
+
+            return variantContent.variants || [];
+          })
           .filter((variant: OpenApiFieldVariant) => variant.fields.length > 0)
       : [];
 
@@ -773,6 +1006,7 @@ function addSecurityFields(args: {
       fieldData.name = "Authorization";
 
       if (scheme.scheme === "bearer") {
+        fieldData.valuePrefix = "Bearer";
         fieldData.description =
           fieldData.description || "Bearer token authentication.";
       } else if (scheme.scheme === "basic") {
@@ -784,6 +1018,7 @@ function addSecurityFields(args: {
       args.requestFields.header.push(fieldData);
     } else if (scheme.type === "oauth2" || scheme.type === "openIdConnect") {
       fieldData.name = "Authorization";
+      fieldData.valuePrefix = "Bearer";
       fieldData.description = fieldData.description || "OAuth2 Bearer Token.";
 
       args.requestFields.header.push(fieldData);
@@ -801,6 +1036,7 @@ function buildOpenApiRequestModel(args: {
   >;
   bodyDescription: string;
   bodyDefaultKind?: OpenApiBodyDefaultKind;
+  requestBodyContentType?: string;
 } {
   const requestFields = createEmptyRequestFields();
   const requestSectionVariants: Partial<
@@ -808,6 +1044,7 @@ function buildOpenApiRequestModel(args: {
   > = {};
   let bodyDescription = "";
   let bodyDefaultKind: OpenApiBodyDefaultKind | undefined = undefined;
+  let requestBodyContentType: string | undefined = undefined;
 
   addSecurityFields({
     operation: args.operation,
@@ -818,26 +1055,15 @@ function buildOpenApiRequestModel(args: {
   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 = {
+    const field = createOpenApiFieldFromSchema({
       name: param.name,
       required: param.required || false,
-      type: getSchemaTypeLabel(schema),
+      schema,
+      seen: new Set<any>(),
       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);
@@ -846,8 +1072,19 @@ function buildOpenApiRequestModel(args: {
   });
 
   if (args.operation.hasRequestBody()) {
-    const requestBody = args.operation.getRequestBody("application/json");
     const requestBodyObject = args.operation.schema.requestBody;
+    const contentTypes = Object.keys(requestBodyObject?.content || {});
+    requestBodyContentType =
+      contentTypes.find((contentType) =>
+        contentType.toLowerCase().includes("application/json"),
+      ) ||
+      contentTypes.find((contentType) =>
+        contentType.toLowerCase().includes("multipart/form-data"),
+      ) ||
+      contentTypes[0];
+    const requestBody = requestBodyContentType
+      ? args.operation.getRequestBody(requestBodyContentType)
+      : undefined;
     const bodySchema = (requestBody as any)?.schema as any;
     bodyDescription =
       requestBodyObject?.description ||
@@ -871,6 +1108,7 @@ function buildOpenApiRequestModel(args: {
     requestSectionVariants,
     bodyDescription,
     bodyDefaultKind,
+    requestBodyContentType,
   };
 }
 

package/template/src/lib/openapi/response-content.ts

@@ -0,0 +1,133 @@
+export interface OpenApiResponseContentEntry {
+  contentType: string;
+  schema: any;
+}
+
+export interface OpenApiBinaryResponseSummary {
+  title: string;
+  description: string;
+  contentTypes: string[];
+  snippetText: string;
+}
+
+function getBaseContentType(contentType: string): string {
+  return String(contentType || "").split(";")[0].trim().toLowerCase();
+}
+
+function isMediaContentType(contentType: string): boolean {
+  const baseContentType = getBaseContentType(contentType);
+  return (
+    baseContentType.startsWith("audio/") ||
+    baseContentType.startsWith("image/") ||
+    baseContentType.startsWith("video/")
+  );
+}
+
+function getMediaKind(contentType: string): "audio" | "image" | "video" | null {
+  const baseContentType = getBaseContentType(contentType);
+  if (baseContentType.startsWith("audio/")) return "audio";
+  if (baseContentType.startsWith("image/")) return "image";
+  if (baseContentType.startsWith("video/")) return "video";
+  return null;
+}
+
+function isKnownBinaryContentType(contentType: string): boolean {
+  const baseContentType = getBaseContentType(contentType);
+  return (
+    isMediaContentType(baseContentType) ||
+    baseContentType === "application/octet-stream" ||
+    baseContentType === "application/pdf" ||
+    baseContentType === "application/zip" ||
+    baseContentType === "application/gzip"
+  );
+}
+
+function isBinarySchema(schema: any, seen = new Set<any>()): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  if (seen.has(schema)) return false;
+
+  const nextSeen = new Set(seen);
+  nextSeen.add(schema);
+
+  if (schema.type === "string" && schema.format === "binary") return true;
+
+  if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf)) {
+    const variants = Array.isArray(schema.oneOf) ? schema.oneOf : schema.anyOf;
+    return variants.some((variant: any) => isBinarySchema(variant, nextSeen));
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    return schema.allOf.some((part: any) => isBinarySchema(part, nextSeen));
+  }
+
+  return false;
+}
+
+function formatContentTypes(contentTypes: string[]): string {
+  if (contentTypes.length <= 1) return contentTypes[0] || "binary content";
+  if (contentTypes.length === 2) return `${contentTypes[0]} or ${contentTypes[1]}`;
+  return `${contentTypes.slice(0, -1).join(", ")}, or ${contentTypes.at(-1)}`;
+}
+
+function getBinaryTitle(contentTypes: string[]): string {
+  const mediaKinds = Array.from(
+    new Set(
+      contentTypes
+        .map((contentType) => getMediaKind(contentType))
+        .filter((kind): kind is "audio" | "image" | "video" => Boolean(kind)),
+    ),
+  );
+
+  if (mediaKinds.length === 1) {
+    const [kind] = mediaKinds;
+    return `Binary ${kind} response`;
+  }
+
+  if (mediaKinds.length > 1) return "Binary media response";
+  return "Binary file response";
+}
+
+export function getResponseContentEntries(
+  response: any,
+): OpenApiResponseContentEntry[] {
+  const content = response?.content;
+  if (!content || typeof content !== "object") return [];
+
+  return Object.entries(content).map(([contentType, mediaType]: [string, any]) => ({
+    contentType,
+    schema: mediaType?.schema,
+  }));
+}
+
+export function getBinaryResponseSummary(
+  response: any,
+): OpenApiBinaryResponseSummary | undefined {
+  const entries = getResponseContentEntries(response);
+  const binaryEntries = entries.filter((entry) => {
+    return (
+      isBinarySchema(entry.schema) || isKnownBinaryContentType(entry.contentType)
+    );
+  });
+
+  if (binaryEntries.length === 0) return undefined;
+
+  const mediaEntries = binaryEntries.filter((entry) =>
+    isMediaContentType(entry.contentType),
+  );
+  const displayEntries = mediaEntries.length > 0 ? mediaEntries : binaryEntries;
+  const contentTypes = Array.from(
+    new Set(displayEntries.map((entry) => getBaseContentType(entry.contentType))),
+  );
+  const title = getBinaryTitle(contentTypes);
+  const formattedTypes = formatContentTypes(contentTypes);
+  const description = `Returns ${formattedTypes} as raw response bytes. The body is not a structured JSON object.`;
+  const contentTypeLabel =
+    contentTypes.length === 1 ? "Content-Type" : "Content-Types";
+
+  return {
+    title,
+    description,
+    contentTypes,
+    snippetText: `${title}\n${contentTypeLabel}: ${contentTypes.join(", ")}\n\nThe response body is raw bytes, not a JSON object.`,
+  };
+}