From e66191d53f7bc52dfa9f37266e5bbe9a60f45bdc Mon Sep 17 00:00:00 2001
From: Devis Lucato <dluc@users.noreply.github.com>
Date: Thu, 8 May 2025 12:38:41 -0700
Subject: [PATCH] =?UTF-8?q?Fix=20upload=20OpenAPI=20specs=20of=20=E2=80=9C?=
 =?UTF-8?q?tags=E2=80=9D=20and=20=E2=80=9Csteps=E2=80=9D=20fields?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 service/Service.AspNetCore/WebAPIEndpoints.cs | 29 +++++++++++++++----
 swagger.json                                  | 28 ++++++++++++++----
 tools/km-cli/upload-file.sh                   | 14 +++++++--
 3 files changed, 58 insertions(+), 13 deletions(-)

diff --git a/service/Service.AspNetCore/WebAPIEndpoints.cs b/service/Service.AspNetCore/WebAPIEndpoints.cs
index d64623e93..bb29917fe 100644
--- a/service/Service.AspNetCore/WebAPIEndpoints.cs
+++ b/service/Service.AspNetCore/WebAPIEndpoints.cs
@@ -20,6 +20,7 @@
 using Microsoft.KernelMemory.DocumentStorage;
 using Microsoft.KernelMemory.HTTP;
 using Microsoft.KernelMemory.Service.AspNetCore.Models;
+using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
 
 namespace Microsoft.KernelMemory.Service.AspNetCore;
@@ -108,8 +109,7 @@ public static RouteHandlerBuilder AddPostUploadEndpoint(
             })
             .WithName("UploadDocument")
             .WithDisplayName("UploadDocument")
-            .WithOpenApi(
-                operation =>
+            .WithOpenApi(operation =>
                 {
                     operation.Summary = "Upload a new document to the knowledge base";
                     operation.Description = "Upload a document consisting of one or more files to extract memories from. The extraction process happens asynchronously. If a document with the same ID already exists, it will be overwritten and the memories previously extracted will be updated.";
@@ -136,15 +136,27 @@ public static RouteHandlerBuilder AddPostUploadEndpoint(
                                         },
                                         ["tags"] = new OpenApiSchema
                                         {
-                                            Type = "object",
-                                            AdditionalProperties = new OpenApiSchema { Type = "string" },
-                                            Description = "Tags to apply to the memories extracted from the files."
+                                            Type = "array",
+                                            Items = new OpenApiSchema { Type = "string" },
+                                            Description = "Tags to apply to the memories extracted from the files.",
+                                            Example = new OpenApiArray
+                                            {
+                                                new OpenApiString("group:abc123"),
+                                                new OpenApiString("user:xyz")
+                                            }
                                         },
                                         ["steps"] = new OpenApiSchema
                                         {
                                             Type = "array",
                                             Items = new OpenApiSchema { Type = "string" },
-                                            Description = "How to process the files, e.g. how to extract/chunk etc."
+                                            Description = "How to process the files, e.g. how to extract/chunk etc.",
+                                            Example = new OpenApiArray
+                                            {
+                                                new OpenApiString("extract"),
+                                                new OpenApiString("partition"),
+                                                new OpenApiString("gen_embeddings"),
+                                                new OpenApiString("save_records"),
+                                            }
                                         },
                                         ["files"] = new OpenApiSchema
                                         {
@@ -157,6 +169,11 @@ public static RouteHandlerBuilder AddPostUploadEndpoint(
                                             Description = "Files to process and extract memories from."
                                         }
                                     }
+                                },
+                                Encoding =
+                                {
+                                    { "tags", new OpenApiEncoding { Explode = true } },
+                                    { "steps", new OpenApiEncoding { Explode = true } },
                                 }
                             }
                         },
diff --git a/swagger.json b/swagger.json
index 7a7a0c99a..7168a2fab 100644
--- a/swagger.json
+++ b/swagger.json
@@ -1,5 +1,5 @@
 {
-  "openapi": "3.0.1",
+  "openapi": "3.0.4",
   "info": {
     "title": "Microsoft.KernelMemory.ServiceAssembly",
     "version": "1.0"
@@ -113,18 +113,28 @@
                     "description": "Unique ID used for import pipeline and document ID."
                   },
                   "tags": {
-                    "type": "object",
-                    "additionalProperties": {
+                    "type": "array",
+                    "items": {
                       "type": "string"
                     },
-                    "description": "Tags to apply to the memories extracted from the files."
+                    "description": "Tags to apply to the memories extracted from the files.",
+                    "example": [
+                      "group:abc123",
+                      "user:xyz"
+                    ]
                   },
                   "steps": {
                     "type": "array",
                     "items": {
                       "type": "string"
                     },
-                    "description": "How to process the files, e.g. how to extract/chunk etc."
+                    "description": "How to process the files, e.g. how to extract/chunk etc.",
+                    "example": [
+                      "extract",
+                      "partition",
+                      "gen_embeddings",
+                      "save_records"
+                    ]
                   },
                   "files": {
                     "type": "array",
@@ -135,6 +145,14 @@
                     "description": "Files to process and extract memories from."
                   }
                 }
+              },
+              "encoding": {
+                "tags": {
+                  "explode": true
+                },
+                "steps": {
+                  "explode": true
+                }
               }
             }
           }
diff --git a/tools/km-cli/upload-file.sh b/tools/km-cli/upload-file.sh
index 1a1c5f06f..3dd65dc73 100755
--- a/tools/km-cli/upload-file.sh
+++ b/tools/km-cli/upload-file.sh
@@ -56,7 +56,7 @@ readParameters() {
             ;;
             -t)
                 shift
-                TAGS="$TAGS $1"
+                TAGS+=("$1")
             ;;
             *)
                 help
@@ -102,7 +102,17 @@ readParameters "$@"
 validateParameters
 
 # Prepare curl command
-CMD="curl -v -F 'file1=@\"${FILENAME}\"' -F 'index=\"${INDEXNAME}\"' -F 'documentId=\"${DOCUMENT_ID}\"' -F 'tags=\"${TAGS}\"'"
+CMD="curl -v"
+CMD="$CMD -F file1=@\"${FILENAME}\""
+
+# Optianal params
+[ -n "$INDEXNAME" ] && CMD="$CMD -F index=\"${INDEXNAME}\""
+[ -n "$DOCUMENT_ID" ] && CMD="$CMD -F documentId=\"${DOCUMENT_ID}\""
+
+# Add tags
+for TAG in "${TAGS[@]}"; do
+    CMD="$CMD -F tags=\"$TAG\""
+done
 
 # Add URL
 CMD="$CMD $SERVICE_URL/upload"