Fix duplicate entity groups in Swagger UI when entities have descriptions

src/Core/Services/OpenAPI/OpenApiDocumentor.cs

@@ -201,7 +201,9 @@ private OpenApiDocument BuildOpenApiDocument(RuntimeConfig runtimeConfig, string
                 Schemas = CreateComponentSchemas(runtimeConfig.Entities, runtimeConfig.DefaultDataSourceName, role, isRequestBodyStrict: runtimeConfig.IsRequestBodyStrict)
             };
 
-            List<OpenApiTag> globalTags = new();
+            // Store tags in a dictionary keyed by normalized REST path to ensure we can
+            // reuse the same tag instances in BuildPaths, preventing duplicate groups in Swagger UI.
+            Dictionary<string, OpenApiTag> globalTagsDict = new();
             foreach (KeyValuePair<string, Entity> kvp in runtimeConfig.Entities)
             {
                 Entity entity = kvp.Value;
@@ -210,8 +212,12 @@ private OpenApiDocument BuildOpenApiDocument(RuntimeConfig runtimeConfig, string
                     continue;
                 }
 
-                string restPath = entity.Rest?.Path ?? kvp.Key;
-                globalTags.Add(new OpenApiTag
+                // Use GetEntityRestPath to ensure consistent path normalization (with leading slash trimmed)
+                // matching the same computation used in BuildPaths.
+                string restPath = GetEntityRestPath(entity.Rest, kvp.Key);
+
+                // First entity's description wins when multiple entities share the same REST path.
+                globalTagsDict.TryAdd(restPath, new OpenApiTag
                 {
                     Name = restPath,
                     Description = string.IsNullOrWhiteSpace(entity.Description) ? null : entity.Description
@@ -229,9 +235,9 @@ private OpenApiDocument BuildOpenApiDocument(RuntimeConfig runtimeConfig, string
                 {
                     new() { Url = url }
                 },
-                Paths = BuildPaths(runtimeConfig.Entities, runtimeConfig.DefaultDataSourceName, role),
+                Paths = BuildPaths(runtimeConfig.Entities, runtimeConfig.DefaultDataSourceName, globalTagsDict, role),
                 Components = components,
-                Tags = globalTags
+                Tags = globalTagsDict.Values.ToList()
             };
         }
 
@@ -291,9 +297,10 @@ public void CreateDocument(bool doOverrideExistingDocument = false)
         /// A path with no primary key nor parameter representing the primary key value:
         /// "/EntityName"
         /// </example>
+        /// <param name="globalTags">Dictionary of global tags keyed by normalized REST path for reuse.</param>
         /// <param name="role">Optional role to filter permissions. If null, returns superset of all roles.</param>
         /// <returns>All possible paths in the DAB engine's REST API endpoint.</returns>
-        private OpenApiPaths BuildPaths(RuntimeEntities entities, string defaultDataSourceName, string? role = null)
+        private OpenApiPaths BuildPaths(RuntimeEntities entities, string defaultDataSourceName, Dictionary<string, OpenApiTag> globalTags, string? role = null)
         {
             OpenApiPaths pathsCollection = new();
 
@@ -327,18 +334,17 @@ private OpenApiPaths BuildPaths(RuntimeEntities entities, string defaultDataSour
                     continue;
                 }
 
-                // Set the tag's Description property to the entity's semantic description if present.
-                OpenApiTag openApiTag = new()
+                // Reuse the existing tag from the global tags dictionary instead of creating a new instance.
+                // This ensures Swagger UI displays only one group per entity by using the same object reference.
+                if (!globalTags.TryGetValue(entityRestPath, out OpenApiTag? existingTag))
                 {
-                    Name = entityRestPath,
-                    Description = string.IsNullOrWhiteSpace(entity.Description) ? null : entity.Description
-                };
+                    _logger.LogWarning("Tag for REST path '{EntityRestPath}' not found in global tags dictionary. This indicates a key mismatch between BuildOpenApiDocument and BuildPaths.", entityRestPath);
+                    continue;
+                }
 
-                // The OpenApiTag will categorize all paths created using the entity's name or overridden REST path value.
-                // The tag categorization will instruct OpenAPI document visualization tooling to display all generated paths together.
                 List<OpenApiTag> tags = new()
                 {
-                    openApiTag
+                    existingTag
                 };
 
                 Dictionary<OperationType, bool> configuredRestOperations = GetConfiguredRestOperations(entity, dbObject, role);

src/Service.Tests/OpenApiDocumentor/StoredProcedureGeneration.cs

@@ -149,6 +149,43 @@ public void OpenApiDocumentor_TagsIncludeEntityDescription()
                 $"Expected tag for '{entityName}' with description '{expectedDescription}' not found.");
         }
 
+        /// <summary>
+        /// Integration test validating that there are no duplicate tags in the OpenAPI document.
+        /// This test ensures that tags created in CreateDocument are reused in BuildPaths,
+        /// preventing Swagger UI from showing duplicate entity groups.
+        /// </summary>
+        [TestMethod]
+        public void OpenApiDocumentor_NoDuplicateTags()
+        {
+            // Act: Get the tags from the OpenAPI document
+            IList<OpenApiTag> tags = _openApiDocument.Tags;
+
+            // Get all tag names
+            List<string> tagNames = tags.Select(t => t.Name).ToList();
+
+            // Get distinct tag names
+            List<string> distinctTagNames = tagNames.Distinct().ToList();
+
+            // Assert: The number of tags should equal the number of distinct tag names (no duplicates)
+            Assert.AreEqual(distinctTagNames.Count, tagNames.Count,
+                $"Duplicate tags found in OpenAPI document. Tags: {string.Join(", ", tagNames)}");
+
+            // Additionally, verify that each operation references tags that are in the global tags list
+            foreach (KeyValuePair<string, OpenApiPathItem> path in _openApiDocument.Paths)
+            {
+                foreach (KeyValuePair<OperationType, OpenApiOperation> operation in path.Value.Operations)
+                {
+                    foreach (OpenApiTag operationTag in operation.Value.Tags)
+                    {
+                        // Verify that the operation's tag is the same instance as one in the global tags
+                        bool foundMatchingTag = tags.Any(globalTag => ReferenceEquals(globalTag, operationTag));
+                        Assert.IsTrue(foundMatchingTag,
+                            $"Operation tag '{operationTag.Name}' at path '{path.Key}' is not the same instance as the global tag");
+                    }
+                }
+            }
+        }
+
         /// <summary>
         /// Validates that the provided OpenApiReference object has the expected schema reference id
         /// and that that id is present in the list of component schema in the OpenApi document.