[API explorer] Add support for x-tagGroups (#3160)

Author: lcawl

docs/configure/content-set/api-explorer.md

@@ -119,7 +119,7 @@ The API Explorer supports the following OpenAPI specification extensions to enha
 
 ### `x-displayName` for tags
 
-Use the `x-displayName` extension on tag objects to provide user-friendly display names in navigation and landing pages while maintaining stable URLs based on the canonical tag name.
+Use the `x-displayName` extension (from [Redocly](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-display-name)) on tag objects to provide user-friendly display names in navigation and landing pages while maintaining stable URLs based on the canonical tag name.
 
 ```json
 {
@@ -139,7 +139,35 @@ Use the `x-displayName` extension on tag objects to provide user-friendly displa
 ```
 
 **Behavior:**
+
 - When `x-displayName` is present, it's used for navigation titles and section headings in the API Explorer
 - When `x-displayName` is absent, the canonical tag `name` is used as a fallback
 - Navigation URLs and internal references always use the canonical tag `name` for stability
-- This extension follows the [Redocly specification extension pattern](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-display-name)
+
+### `x-tagGroups` for sidebar grouping
+
+Use the document-level `x-tagGroups` extension (from [Redocly](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-tag-groups)) to define how tags are grouped in the API Explorer sidebar. Each group has a display `name` and a list of tag `name` values that belong to it. Group order in the array is the order of top-level sections in the navigation.
+
+```json
+{
+  "openapi": "3.0.3",
+  "info": { "title": "Example", "version": "1.0.0" },
+  "paths": {},
+  "x-tagGroups": [
+    {
+      "name": "Search & Document APIs",
+      "tags": ["search", "document", "eql", "esql", "sql"]
+    },
+    {
+      "name": "Cluster Management",
+      "tags": ["indices", "cluster", "snapshot"]
+    }
+  ]
+}
+```
+
+**Behavior:**
+
+- When `x-tagGroups` is present and valid, the API Explorer uses it as an additional level of grouping in the sidebar.
+- When `x-tagGroups` is absent, tags are listed directly under the API root in a single flat layer.
+- Any operation tag that is not listed under any group is still included: it appears under a fallback section named `unknown`, and the build logs a warning so you can fix the spec.

src/Elastic.ApiExplorer/OpenApiGenerator.cs

@@ -4,6 +4,7 @@
 
 using System;
 using System.IO.Abstractions;
+using System.Text.Json.Nodes;
 using System.Text.RegularExpressions;
 using Elastic.ApiExplorer.Landing;
 using Elastic.ApiExplorer.Operations;
@@ -44,6 +45,9 @@ public record ApiEndpoint(List<ApiOperation> Operations, string? Name) : IApiGro
 
 public class OpenApiGenerator(ILoggerFactory logFactory, BuildContext context, IMarkdownStringRenderer markdownStringRenderer)
 {
+	private const string TagOnlyClassificationKey = "__api_explorer_tag_only__";
+	private const string UnknownTagGroupName = "unknown";
+
 	private readonly ILogger _logger = logFactory.CreateLogger<OpenApiGenerator>();
 	private readonly IFileSystem _writeFileSystem = context.WriteFileSystem;
 	private readonly StaticFileContentHashProvider _contentHashProvider = new(new EmbeddedOrPhysicalFileProvider(context));
@@ -56,6 +60,8 @@ public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocume
 
 		// Parse x-displayName from OpenAPI tags for user-friendly display names
 		var tagDisplayNames = ParseTagDisplayNames(openApiDocument);
+		var xTagGroups = TryParseXTagGroups(openApiDocument);
+		var orphanTagsLogged = new HashSet<string>(StringComparer.Ordinal);
 
 		var ops = openApiDocument.Paths
 			.SelectMany(p => (p.Value.Operations ?? []).Select(op => (Path: p, Operation: op)))
@@ -70,11 +76,7 @@ public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocume
 					? anyApi.Node.GetValue<string>()
 					: null;
 				var tag = op.Value.Tags?.FirstOrDefault()?.Reference.Id;
-				var tagClassification = (extensions?.TryGetValue("x-tag-group", out var g) ?? false) && g is JsonNodeExtension anyTagGroup
-					? anyTagGroup.Node.GetValue<string>()
-					: openApiDocument.Info.Title == "Elasticsearch Request & Response Specification"
-						? ClassifyElasticsearchTag(tag ?? "unknown")
-						: "unknown";
+				var tagClassification = ResolveTagClassification(tag, xTagGroups, orphanTagsLogged);
 
 				var apiString = ns is null
 					? api ?? op.Value.Summary ?? Guid.NewGuid().ToString("N") : $"{ns}.{api}";
@@ -91,11 +93,20 @@ public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocume
 
 		// intermediate grouping of models to create the navigation tree
 		// this is two-phased because we need to know if an endpoint has one or more operations
+		var presentClassifications = ops.Select(o => o.Classification).ToHashSet();
+		var orderedClassificationKeys = xTagGroups is null
+			? [TagOnlyClassificationKey]
+			: GetOrderedClassificationKeys(xTagGroups, presentClassifications);
+
 		var classifications = new List<ApiClassification>();
-		foreach (var classGroup in ops.GroupBy(o => o.Classification))
+		foreach (var classKey in orderedClassificationKeys)
 		{
+			var classOps = ops.Where(o => o.Classification == classKey).ToArray();
+			if (classOps.Length == 0)
+				continue;
+
 			var tags = new List<ApiTag>();
-			foreach (var tagGroup in classGroup.GroupBy(o => o.Tag))
+			foreach (var tagGroup in classOps.GroupBy(o => o.Tag))
 			{
 				var apis = new List<ApiEndpoint>();
 				foreach (var apiGroup in tagGroup.GroupBy(o => o.Api))
@@ -119,15 +130,14 @@ public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocume
 			// Sort tags alphabetically by display name, fallback to canonical name
 			tags = tags.OrderBy(t => t.DisplayName ?? t.Name, StringComparer.OrdinalIgnoreCase).ToList();
 
-			var classification = new ApiClassification(classGroup.Key, "", tags);
-			classifications.Add(classification);
+			classifications.Add(new ApiClassification(classKey, "", tags));
 		}
 
 		var topLevelNavigationItems = new List<IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem>>();
 		var hasClassifications = classifications.Count > 1;
 		foreach (var classification in classifications)
 		{
-			if (hasClassifications && classification.Name != "common")
+			if (hasClassifications)
 			{
 				var classificationNavigationItem = new ClassificationNavigationItem(classification, rootNavigation, rootNavigation);
 				var tagNavigationItems = new List<IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem>>();
@@ -406,72 +416,95 @@ private static string FormatSchemaDisplayName(string schemaId)
 		return parts.Length > 0 ? parts[^1] : schemaId;
 	}
 
-	private static string ClassifyElasticsearchTag(string tag)
+	private string ResolveTagClassification(string? tag, XTagGroupsDocument? xTagGroups, HashSet<string> orphanTagsLogged)
 	{
-#pragma warning disable IDE0066
-		switch (tag)
-#pragma warning restore IDE0066
+		if (xTagGroups is null)
+			return TagOnlyClassificationKey;
+
+		var tagName = tag ?? UnknownTagGroupName;
+		if (xTagGroups.TagToGroup.TryGetValue(tagName, out var group))
+			return group;
+
+		if (orphanTagsLogged.Add(tagName))
 		{
-			case "sql":
-			case "eql":
-			case "esql":
-			case "search":
-			case "document":
-				return "common";
-
-			case "autoscaling":
-			case "ccr":
-			case "indices":
-			case "data stream":
-			case "ilm":
-			case "slm":
-			case "cluster":
-			case "rollup":
-			case "searchable_snapshots":
-			case "shutdown":
-			case "snapshot":
-			case "script":
-			case "search_application":
-			case "connector":
-				return "management";
-
-			case "cat":
-			case "license":
-			case "info":
-			case "tasks":
-			case "xpack":
-			case "health_report":
-			case "features":
-			case "migration":
-			case "watcher":
-				return "info";
-
-
-			case "ml trained model":
-			case "ml anomaly":
-			case "ml data frame":
-			case "ml":
-			case "inference":
-			case "text_structure":
-			case "query_rules":
-			case "analytics":
-			case "graph":
-				return "ai/ml";
-
-			case "ingest":
-			case "enrich":
-			case "transform":
-			case "fleet":
-			case "logstash":
-			case "synonyms":
-				return "ingest";
-
-			case "security":
-				return "security";
+			_logger.LogWarning(
+				"OpenAPI tag '{TagName}' is not listed in any x-tagGroups entry; navigation will group it under '{UnknownGroup}'.",
+				tagName,
+				UnknownTagGroupName);
 		}
-		return "unknown";
+
+		return UnknownTagGroupName;
 	}
 
+	private static List<string> GetOrderedClassificationKeys(XTagGroupsDocument xTagGroups, HashSet<string> presentClassifications)
+	{
+		var ordered = new List<string>();
+		foreach (var g in xTagGroups.OrderedGroupNames)
+		{
+			if (presentClassifications.Contains(g))
+				ordered.Add(g);
+		}
+
+		if (presentClassifications.Contains(UnknownTagGroupName) && !ordered.Contains(UnknownTagGroupName))
+			ordered.Add(UnknownTagGroupName);
+
+		foreach (var c in presentClassifications)
+		{
+			if (!ordered.Contains(c))
+				ordered.Add(c);
+		}
+
+		return ordered;
+	}
+
+	private static XTagGroupsDocument? TryParseXTagGroups(OpenApiDocument openApiDocument)
+	{
+		if (openApiDocument.Extensions?.TryGetValue("x-tagGroups", out var extension) != true || extension is not JsonNodeExtension jsonExt)
+			return null;
+
+		if (jsonExt.Node is not JsonArray array || array.Count == 0)
+			return null;
+
+		var orderedGroupNames = new List<string>();
+		var tagToGroup = new Dictionary<string, string>(StringComparer.Ordinal);
+
+		foreach (var element in array)
+		{
+			if (element is not JsonObject groupObj)
+				continue;
+
+			if (!groupObj.TryGetPropertyValue("name", out var nameNode))
+				continue;
+
+			var groupName = nameNode?.GetValue<string>();
+			if (string.IsNullOrWhiteSpace(groupName))
+				continue;
+
+			if (!orderedGroupNames.Contains(groupName))
+				orderedGroupNames.Add(groupName);
+
+			if (!groupObj.TryGetPropertyValue("tags", out var tagsNode) || tagsNode is not JsonArray tagNames)
+				continue;
+
+			foreach (var tagElement in tagNames)
+			{
+				var tagName = tagElement?.GetValue<string>();
+				if (string.IsNullOrEmpty(tagName))
+					continue;
+
+				if (!tagToGroup.ContainsKey(tagName))
+					tagToGroup[tagName] = groupName;
+			}
+		}
+
+		if (orderedGroupNames.Count == 0 || tagToGroup.Count == 0)
+			return null;
+
+		return new XTagGroupsDocument(orderedGroupNames, tagToGroup);
+	}
+
+	private sealed record XTagGroupsDocument(IReadOnlyList<string> OrderedGroupNames, IReadOnlyDictionary<string, string> TagToGroup);
+
 	/// <summary>
 	/// Parses x-displayName extensions from OpenAPI tag objects to build a mapping of tag names to display names.
 	/// Falls back to the canonical tag name when no x-displayName is present.