fix(theme): improve nested discriminator handling and examples

Handle recursively nested discriminators in composed schemas while preserving intentional empty-object rendering, and add demo specs covering deep allOf discriminator chains and explicit empty object properties.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sserrata

demo/examples/tests/allOf.yaml

@@ -510,6 +510,39 @@ paths:
                   name:
                     type: string
 
+  /allof-empty-object-properties:
+    get:
+      tags:
+        - allOf
+      summary: allOf with explicit empty object properties
+      description: |
+        Demonstrates an intentional empty object schema (properties: {}) to ensure
+        the renderer still shows the object shape rather than hiding it.
+
+        Schema:
+        ```yaml
+        type: object
+        properties:
+          metadata:
+            type: object
+            properties: {}
+          name:
+            type: string
+        ```
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  metadata:
+                    type: object
+                    properties: {}
+                  name:
+                    type: string
+
   /allof-multiple-oneof:
     post:
       tags:

demo/examples/tests/discriminator.yaml

@@ -417,6 +417,32 @@ paths:
               schema:
                 $ref: "#/components/schemas/DoublyNestedBase"
 
+  /discriminator-deeply-nested-allof:
+    post:
+      tags:
+        - discriminator
+      summary: Deeply Nested Discriminator in allOf chains
+      description: |
+        Tests discriminator discovery through nested allOf chains:
+        - top-level allOf
+        - inner allOf
+        - oneOf with discriminator
+
+        This validates recursive discriminator lookup beyond first-level allOf items.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeepNestedDiscriminatorBase"
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeepNestedDiscriminatorBase"
+
 components:
   schemas:
     BaseBasic:
@@ -664,6 +690,57 @@ components:
               variant-a: "#/components/schemas/NestedVariantA"
               variant-b: "#/components/schemas/NestedVariantB"
 
+    DeepNestedDiscriminatorBase:
+      allOf:
+        - $ref: "#/components/schemas/CommonProps"
+        - allOf:
+            - $ref: "#/components/schemas/DeepLayerCommon"
+            - oneOf:
+                - $ref: "#/components/schemas/DeepNestedVariantA"
+                - $ref: "#/components/schemas/DeepNestedVariantB"
+              discriminator:
+                propertyName: deepVariantType
+                mapping:
+                  deep-a: "#/components/schemas/DeepNestedVariantA"
+                  deep-b: "#/components/schemas/DeepNestedVariantB"
+
+    DeepLayerCommon:
+      type: object
+      properties:
+        layer:
+          type: string
+          enum: ["inner"]
+      required:
+        - layer
+
+    DeepNestedVariantA:
+      type: object
+      properties:
+        deepVariantType:
+          type: string
+          enum: ["deep-a"]
+        deepAConfig:
+          type: object
+          properties:
+            enabled:
+              type: boolean
+      required:
+        - deepVariantType
+
+    DeepNestedVariantB:
+      type: object
+      properties:
+        deepVariantType:
+          type: string
+          enum: ["deep-b"]
+        deepBConfig:
+          type: object
+          properties:
+            threshold:
+              type: number
+      required:
+        - deepVariantType
+
     NestedVariantA:
       type: object
       properties:

packages/docusaurus-theme-openapi-docs/src/theme/Schema/index.tsx

@@ -85,6 +85,39 @@ const findProperty = (
   return undefined;
 };
 
+/**
+ * Recursively searches for a discriminator in a schema, including nested
+ * oneOf, anyOf, and allOf structures.
+ */
+const findDiscriminator = (schema: SchemaObject): any | undefined => {
+  if (schema.discriminator) {
+    return schema.discriminator;
+  }
+
+  if (schema.oneOf) {
+    for (const subschema of schema.oneOf) {
+      const found = findDiscriminator(subschema as SchemaObject);
+      if (found) return found;
+    }
+  }
+
+  if (schema.anyOf) {
+    for (const subschema of schema.anyOf) {
+      const found = findDiscriminator(subschema as SchemaObject);
+      if (found) return found;
+    }
+  }
+
+  if (schema.allOf) {
+    for (const subschema of schema.allOf) {
+      const found = findDiscriminator(subschema as SchemaObject);
+      if (found) return found;
+    }
+  }
+
+  return undefined;
+};
+
 interface MarkdownProps {
   text: string | undefined;
 }
@@ -354,10 +387,21 @@ const Properties: React.FC<SchemaProps> = ({
     discriminator["mapping"] = inferredMapping;
   }
   if (Object.keys(schema.properties as {}).length === 0) {
-    // If properties are empty (e.g., after discriminator property removal in oneOf),
-    // don't render an empty "object" placeholder - just return nothing
-    // This prevents confusing empty object displays in discriminated unions
-    return null;
+    // Hide placeholder only for discriminator cleanup artifacts; preserve
+    // empty object rendering for schemas that intentionally define no properties.
+    if (discriminator) {
+      return null;
+    }
+    return (
+      <SchemaItem
+        collapsible={false}
+        name=""
+        required={false}
+        schemaName="object"
+        qualifierMessage={undefined}
+        schema={{}}
+      />
+    );
   }
 
   return (
@@ -1031,22 +1075,16 @@ const SchemaNode: React.FC<SchemaProps> = ({
     return null;
   }
 
-  // Merge allOf first if present, so discriminators in nested schemas are properly handled
-  // This ensures discriminator property lookups work for schemas like:
-  // allOf: [{ $ref: CommonProps }, { oneOf: [...], discriminator: {...} }]
+  // Resolve discriminator recursively so nested oneOf/anyOf/allOf compositions
+  // can still render discriminator tabs.
   let workingSchema = schema;
-  if (schema.allOf && !schema.discriminator) {
-    // Check if any allOf item has a discriminator that should be hoisted
-    const discriminatorItem = schema.allOf.find(
-      (item: any) => item.discriminator
-    );
-    if (discriminatorItem) {
-      workingSchema = mergeAllOf(schema) as SchemaObject;
-      // Preserve the discriminator from the nested schema
-      if (!workingSchema.discriminator && discriminatorItem.discriminator) {
-        workingSchema.discriminator = discriminatorItem.discriminator;
-      }
-    }
+  const resolvedDiscriminator =
+    schema.discriminator ?? findDiscriminator(schema);
+  if (schema.allOf && !schema.discriminator && resolvedDiscriminator) {
+    workingSchema = mergeAllOf(schema) as SchemaObject;
+  }
+  if (!workingSchema.discriminator && resolvedDiscriminator) {
+    workingSchema.discriminator = resolvedDiscriminator;
   }
 
   if (workingSchema.discriminator) {