From 5c9b27e6e7802fb008e74b24eb482aa51bc4710f Mon Sep 17 00:00:00 2001
From: bymyself <cbyrne@comfy.org>
Date: Mon, 14 Jul 2025 15:53:22 -0700
Subject: [PATCH] [openapi] Improve queue item structure with proper schema

Replace generic additionalProperties: true for queue items with
detailed QueueItem schema that properly describes the array structure:

- Position number (integer)
- Prompt ID (UUID string)
- Workflow graph (object)
- Extra metadata (object)
- Output node IDs (array)

This provides much better API documentation and validation for
queue responses than the previous generic object definition.
---
 openapi.yaml | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index 464c0e55a..fb2cae917 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -696,15 +696,11 @@ components:
         queue_running:
           type: array
           items:
-            type: object
-            description: Currently running items
-            additionalProperties: true
+            $ref: '#/components/schemas/QueueItem'
         queue_pending:
           type: array
           items:
-            type: object
-            description: Pending items in the queue
-            additionalProperties: true
+            $ref: '#/components/schemas/QueueItem'
     HistoryItem:
       type: object
       properties:
@@ -936,3 +932,23 @@ components:
         enabled:
           type: boolean
           description: Whether to enable or disable subscription
+    QueueItem:
+      type: array
+      description: Queue item containing execution details
+      items:
+        oneOf:
+          - type: integer
+            description: Queue position number
+          - type: string
+            format: uuid
+            description: Unique prompt identifier
+          - type: object
+            description: Workflow graph with nodes and connections
+            additionalProperties: true
+          - type: object
+            description: Extra metadata (auth tokens, client info, etc.)
+            additionalProperties: true
+          - type: array
+            description: Array of output node IDs
+            items:
+              type: string