feat: support allOf, anyOf, and oneOf schemas with properties in array items

Author: dsuket

demo/examples/tests/allOf.yaml

@@ -243,6 +243,76 @@ paths:
                 items:
                   $ref: "#/components/schemas/Book"
 
+  /allof-with-properties-in-array-item:
+    get:
+      tags:
+        - allOf
+      summary: allOf with Properties in Array Item
+      description: |
+        A list of books demonstrating allOf with properties in array item.
+
+        Schema:
+        ```yaml
+        type: array
+        items:
+          $ref: '#/components/schemas/Book'
+        ```
+
+        Schema Components:
+        ```yaml
+        BookBase:
+          type: object
+          required:
+            - id
+            - title
+            - author
+          properties:
+            id:
+              type: integer
+              format: int64
+              description: Unique identifier for the book
+            title:
+              type: string
+              description: The title of the book
+            author:
+              type: string
+              description: The author of the book
+
+        AdditionalBookInfo:
+          type: object
+          properties:
+            publishedDate:
+              type: string
+              format: date
+              description: The date the book was published
+            genre:
+              type: string
+              description: The genre of the book
+            tags:
+              type: array
+              items:
+                type: string
+              description: Tags associated with the book
+
+        CategorizedBook:
+          allOf:
+            - $ref: '#/components/schemas/BookBase'
+            - $ref: '#/components/schemas/AdditionalBookInfo'
+          properties:
+            category:
+              type: string
+              description: The category of the book
+        ```
+      responses:
+        "200":
+          description: A list of books
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/CategorizedBook"
+
   /allof-nested:
     get:
       tags:
@@ -320,12 +390,15 @@ components:
           type: integer
           format: int64
           description: Unique identifier for the book
+          example: 1234567890
         title:
           type: string
           description: The title of the book
+          example: "The Great Gatsby"
         author:
           type: string
           description: The author of the book
+          example: "F. Scott Fitzgerald"
 
     AdditionalBookInfo:
       type: object
@@ -334,16 +407,29 @@ components:
           type: string
           format: date
           description: The date the book was published
+          example: "2021-01-01"
         genre:
           type: string
           description: The genre of the book
+          example: "Fiction"
         tags:
           type: array
           items:
             type: string
           description: Tags associated with the book
+          example: ["Fiction", "Mystery"]
 
     Book:
       allOf:
         - $ref: "#/components/schemas/BookBase"
         - $ref: "#/components/schemas/AdditionalBookInfo"
+
+    CategorizedBook:
+      allOf:
+        - $ref: "#/components/schemas/BookBase"
+        - $ref: "#/components/schemas/AdditionalBookInfo"
+      properties:
+        category:
+          type: string
+          description: The category of the book
+          example: "Fiction"

demo/examples/tests/anyOf.yaml

@@ -61,3 +61,63 @@ paths:
                   - type: boolean
                     title: A boolean
                 title: A string or integer, or a boolean
+
+  /anyof-with-properties-in-array-item:
+    get:
+      tags:
+        - anyOf
+      summary: anyOf with Properties in Array Item
+      description: |
+        Schema:
+        ```yaml
+        type: array
+        items:
+          type: object
+          anyOf:
+            - type: object
+              title: Item
+              properties:
+                orderNo:
+                  type: string
+                  example: "123456"
+            - type: object
+              title: Error
+              properties:
+                error:
+                  type: string
+                  example: "Invalid order number"
+          properties:
+            name:
+              type: string
+              example: pencil
+          required:
+            - orderNo
+        ```
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  anyOf:
+                    - type: object
+                      title: Item
+                      properties:
+                        orderNo:
+                          type: string
+                          example: "123456"
+                    - type: object
+                      title: Error
+                      properties:
+                        error:
+                          type: string
+                          example: "Invalid order number"
+                  properties:
+                    name:
+                      type: string
+                      example: pencil
+                  required:
+                    - orderNo

demo/examples/tests/oneOf.yaml

@@ -262,3 +262,63 @@ paths:
                           requiredPropB:
                             type: number
                         required: ["requiredPropB"]
+
+  /oneof-with-properties-in-array-item:
+    get:
+      tags:
+        - oneOf
+      summary: oneOf with Properties in Array Item
+      description: |
+        Schema:
+        ```yaml
+        type: array
+        items:
+          type: object
+          oneOf:
+            - type: object
+              title: Item
+              properties:
+                orderNo:
+                  type: string
+                  example: "123456"
+            - type: object
+              title: Error
+              properties:
+                error:
+                  type: string
+                  example: "Invalid order number"
+          properties:
+            name:
+              type: string
+              example: pencil
+          required:
+            - orderNo
+        ```
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  oneOf:
+                    - type: object
+                      title: Item
+                      properties:
+                        orderNo:
+                          type: string
+                          example: "123456"
+                    - type: object
+                      title: Error
+                      properties:
+                        error:
+                          type: string
+                          example: "Invalid order number"
+                  properties:
+                    name:
+                      type: string
+                      example: pencil
+                  required:
+                    - orderNo

packages/docusaurus-plugin-openapi-docs/src/openapi/createRequestExample.ts

@@ -174,11 +174,11 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
 
     if (type === "array") {
       if (Array.isArray(items?.anyOf)) {
-        return items?.anyOf.map((item: any) => sampleRequestFromSchema(item));
+        return processArrayItems(items, "anyOf");
       }
 
       if (Array.isArray(items?.oneOf)) {
-        return items?.oneOf.map((item: any) => sampleRequestFromSchema(item));
+        return processArrayItems(items, "oneOf");
       }
 
       return normalizeArray(sampleRequestFromSchema(items));
@@ -233,3 +233,26 @@ function normalizeArray(arr: any) {
   }
   return [arr];
 }
+
+function processArrayItems(
+  items: SchemaObject,
+  schemaType: "anyOf" | "oneOf"
+): any[] {
+  const itemsArray = items[schemaType] as SchemaObject[];
+  return itemsArray.map((item: SchemaObject) => {
+    // If items has properties, merge them with each item
+    if (items.properties) {
+      const combinedSchema = {
+        ...item,
+        properties: {
+          ...items.properties, // Common properties from parent
+          ...item.properties, // Specific properties from this anyOf/oneOf item
+        },
+      };
+      // Remove anyOf/oneOf to prevent infinite recursion when calling sampleRequestFromSchema
+      delete combinedSchema[schemaType];
+      return sampleRequestFromSchema(combinedSchema);
+    }
+    return sampleRequestFromSchema(item);
+  });
+}

packages/docusaurus-plugin-openapi-docs/src/openapi/createResponseExample.ts

@@ -177,11 +177,11 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
 
     if (type === "array") {
       if (Array.isArray(items?.anyOf)) {
-        return items?.anyOf.map((item: any) => sampleResponseFromSchema(item));
+        return processArrayItems(items, "anyOf");
       }
 
       if (Array.isArray(items?.oneOf)) {
-        return items?.oneOf.map((item: any) => sampleResponseFromSchema(item));
+        return processArrayItems(items, "oneOf");
       }
 
       return [sampleResponseFromSchema(items)];
@@ -236,3 +236,26 @@ function normalizeArray(arr: any) {
   }
   return [arr];
 }
+
+function processArrayItems(
+  items: SchemaObject,
+  schemaType: "anyOf" | "oneOf"
+): any[] {
+  const itemsArray = items[schemaType] as SchemaObject[];
+  return itemsArray.map((item: SchemaObject) => {
+    // If items has properties, merge them with each item
+    if (items.properties) {
+      const combinedSchema = {
+        ...item,
+        properties: {
+          ...items.properties, // Common properties from parent
+          ...item.properties, // Specific properties from this anyOf/oneOf item
+        },
+      };
+      // Remove anyOf/oneOf to prevent infinite recursion when calling sampleResponseFromSchema
+      delete combinedSchema[schemaType];
+      return sampleResponseFromSchema(combinedSchema);
+    }
+    return sampleResponseFromSchema(item);
+  });
+}