u

scripts/generateApiDocs.js

@@ -547,6 +547,7 @@ function summarizeSchema(
         const alias = shape && aliases.get(`${markOptional ? 1 : 0}\0${shape}`);
         if (alias && !skipRootAlias) return alias;
 
+        const hasExplicitRequired = Array.isArray(resolved.required);
         const required = new Set(resolved.required || []);
         let entries = Object.entries(resolved.properties || {});
         if (entries.length === 0) {
@@ -558,7 +559,7 @@ function summarizeSchema(
         }
 
         // Required props first, then optional ones (stable within each group).
-        if (markOptional) {
+        if (markOptional || hasExplicitRequired) {
             entries = entries
                 .map(([name], i) => ({ name, i }))
                 .sort((a, b) => (required.has(a.name) ? 0 : 1) - (required.has(b.name) ? 0 : 1) || a.i - b.i)
@@ -566,16 +567,21 @@ function summarizeSchema(
         }
 
         const parts = entries.map(([name, prop]) => {
-            const opt = markOptional && !required.has(name) ? '?' : '';
-            const type = summarizeSchema(prop, components, depth + 1, markOptional, aliases) || 'any';
+            const isOpt = markOptional ? !required.has(name) : (hasExplicitRequired && !required.has(name));
+            const opt = isOpt ? '?' : '';
+            let type = summarizeSchema(prop, components, depth + 1, markOptional, aliases) || 'any';
+            if (prop?.nullable && !type.includes('|null')) {
+                type = `${type}|null`;
+            }
             return `${name}${opt}: ${type}`;
         });
         return `{ ${parts.join(', ')} }`;
     }
 
     if (resolved.type) {
+        let t = resolved.type;
         if (aliases?.compactTypes) {
-            return {
+            t = {
                 string: 'str',
                 integer: 'int',
                 number: 'num',
@@ -583,7 +589,10 @@ function summarizeSchema(
                 object: '{}',
             }[resolved.type] || resolved.type;
         }
-        return resolved.type;
+        if (resolved.nullable && !t.includes('|null')) {
+            t = `${t}|null`;
+        }
+        return t;
     }
     return schemaRefName(schema) || '';
 }