Address code review feedback: fix tag key mismatch and improve code quality

Copilot · JerryNixon · Copilot · commit 46f6a5b02896 · 2026-02-16T19:13:24.000Z
Co-authored-by: JerryNixon &lt;1749983+JerryNixon@users.noreply.github.com&gt;
diff --git a/src/Core/Services/OpenAPI/OpenApiDocumentor.cs b/src/Core/Services/OpenAPI/OpenApiDocumentor.cs
@@ -145,17 +145,16 @@ public void CreateDocument(bool doOverrideExistingDocument = false)
                 foreach (KeyValuePair<string, Entity> kvp in runtimeConfig.Entities)
                 {
                     Entity entity = kvp.Value;
-                    string restPath = entity.Rest?.Path ?? kvp.Key;
+                    // Use GetEntityRestPath to ensure consistent path computation (with leading slash trimmed)
+                    string restPath = GetEntityRestPath(entity.Rest, kvp.Key);
                     
                     // Only add the tag if it hasn't been added yet (handles entities with the same REST path)
-                    if (!globalTagsDict.ContainsKey(restPath))
+                    // First entity's description wins when multiple entities share the same REST path.
+                    globalTagsDict.TryAdd(restPath, new OpenApiTag
                     {
-                        globalTagsDict[restPath] = new OpenApiTag
-                        {
-                            Name = restPath,
-                            Description = string.IsNullOrWhiteSpace(entity.Description) ? null : entity.Description
-                        };
-                    }
+                        Name = restPath,
+                        Description = string.IsNullOrWhiteSpace(entity.Description) ? null : entity.Description
+                    });
                 }
 
                 OpenApiDocument doc = new()
@@ -243,7 +242,9 @@ private OpenApiPaths BuildPaths(RuntimeEntities entities, string defaultDataSour
                 }
                 else
                 {
-                    // Fallback: create a new tag if not found in global tags (should not happen in normal flow)
+                    // Fallback: create a new tag if not found in global tags.
+                    // This should not happen in normal flow if GetEntityRestPath is used consistently.
+                    // If this path is reached, it indicates a key mismatch between CreateDocument and BuildPaths.
                     tags.Add(new OpenApiTag
                     {
                         Name = entityRestPath,
diff --git a/src/Service.Tests/OpenApiDocumentor/StoredProcedureGeneration.cs b/src/Service.Tests/OpenApiDocumentor/StoredProcedureGeneration.cs
@@ -161,21 +161,21 @@ public void OpenApiDocumentor_NoDuplicateTags()
             IList<OpenApiTag> tags = _openApiDocument.Tags;
 
             // Get all tag names
-            var tagNames = tags.Select(t => t.Name).ToList();
+            List<string> tagNames = tags.Select(t => t.Name).ToList();
 
             // Get distinct tag names
-            var distinctTagNames = tagNames.Distinct().ToList();
+            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 (var path in _openApiDocument.Paths)
+            foreach (KeyValuePair<string, OpenApiPathItem> path in _openApiDocument.Paths)
             {
-                foreach (var operation in path.Value.Operations)
+                foreach (KeyValuePair<OperationType, OpenApiOperation> operation in path.Value.Operations)
                 {
-                    foreach (var operationTag in operation.Value.Tags)
+                    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));

Original file line number	Diff line number	Diff line change
`@@ -145,17 +145,16 @@ public void CreateDocument(bool doOverrideExistingDocument = false)`
`145`	`145`	`foreach (KeyValuePair<string, Entity> kvp in runtimeConfig.Entities)`
`146`	`146`	`{`
`147`	`147`	`Entity entity = kvp.Value;`
`148`		`- string restPath = entity.Rest?.Path ?? kvp.Key;`
	`148`	`+ // Use GetEntityRestPath to ensure consistent path computation (with leading slash trimmed)`
	`149`	`+ string restPath = GetEntityRestPath(entity.Rest, kvp.Key);`
`149`	`150`
`150`	`151`	`// Only add the tag if it hasn't been added yet (handles entities with the same REST path)`
`151`		`- if (!globalTagsDict.ContainsKey(restPath))`
	`152`	`+ // First entity's description wins when multiple entities share the same REST path.`
	`153`	`+ globalTagsDict.TryAdd(restPath, new OpenApiTag`
`152`	`154`	`{`
`153`		`- globalTagsDict[restPath] = new OpenApiTag`
`154`		`- {`
`155`		`- Name = restPath,`
`156`		`- Description = string.IsNullOrWhiteSpace(entity.Description) ? null : entity.Description`
`157`		`- };`
`158`		`- }`
	`155`	`+ Name = restPath,`
	`156`	`+ Description = string.IsNullOrWhiteSpace(entity.Description) ? null : entity.Description`
	`157`	`+ });`
`159`	`158`	`}`
`160`	`159`
`161`	`160`	`OpenApiDocument doc = new()`
`@@ -243,7 +242,9 @@ private OpenApiPaths BuildPaths(RuntimeEntities entities, string defaultDataSour`
`243`	`242`	`}`
`244`	`243`	`else`
`245`	`244`	`{`
`246`		`- // Fallback: create a new tag if not found in global tags (should not happen in normal flow)`
	`245`	`+ // Fallback: create a new tag if not found in global tags.`
	`246`	`+ // This should not happen in normal flow if GetEntityRestPath is used consistently.`
	`247`	`+ // If this path is reached, it indicates a key mismatch between CreateDocument and BuildPaths.`
`247`	`248`	`tags.Add(new OpenApiTag`
`248`	`249`	`{`
`249`	`250`	`Name = entityRestPath,`