[API explorer] Add support for tag x-displayName (#3140)

Author: lcawl

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

@@ -112,3 +112,34 @@ The API Explorer generates the following types of pages from your OpenAPI spec:
 - **Landing page**: An overview of the API grouped by tag
 - **Operation pages**: One page per API operation, with the HTTP method, path, parameters, request body, response schemas, and examples
 - **Schema type pages**: Dedicated pages for complex shared types such as `QueryContainer` and `AggregationContainer`
+
+## OpenAPI extensions
+
+The API Explorer supports the following OpenAPI specification extensions to enhance navigation and display:
+
+### `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.
+
+```json
+{
+  "tags": [
+    {
+      "name": "tasks",
+      "description": "The task management APIs enable you to get information about tasks currently running.",
+      "x-displayName": "Task management"
+    },
+    {
+      "name": "ml_anomaly", 
+      "description": "Machine learning anomaly detection APIs.",
+      "x-displayName": "Machine Learning Anomaly Detection"
+    }
+  ]
+}
+```
+
+**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)

src/Elastic.ApiExplorer/Landing/LandingNavigationItem.cs

@@ -117,7 +117,7 @@ public class TagNavigationItem(ApiTag tag, IRootNavigationItem<IApiGroupingModel
 	: ApiGroupingNavigationItem<ApiTag, IEndpointOrOperationNavigationItem>(tag, rootNavigation, parent)
 {
 	/// <inheritdoc />
-	public override string NavigationTitle { get; } = tag.Name;
+	public override string NavigationTitle { get; } = tag.DisplayName;
 
 	/// <inheritdoc />
 	public override string Id { get; } = ShortId.Create(tag.Name);

src/Elastic.ApiExplorer/OpenApiGenerator.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System;
 using System.IO.Abstractions;
 using System.Text.RegularExpressions;
 using Elastic.ApiExplorer.Landing;
@@ -29,7 +30,7 @@ public record ApiClassification(string Name, string Description, IReadOnlyCollec
 	public Task RenderAsync(FileSystemStream stream, ApiRenderContext context, CancellationToken ctx = default) => Task.CompletedTask;
 }
 
-public record ApiTag(string Name, string Description, IReadOnlyCollection<ApiEndpoint> Endpoints) : IApiGroupingModel
+public record ApiTag(string Name, string DisplayName, string Description, IReadOnlyCollection<ApiEndpoint> Endpoints) : IApiGroupingModel
 {
 	/// <inheritdoc />
 	public Task RenderAsync(FileSystemStream stream, ApiRenderContext context, CancellationToken ctx = default) => Task.CompletedTask;
@@ -53,6 +54,9 @@ public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocume
 		var url = $"{context.UrlPathPrefix}/api/" + apiUrlSuffix;
 		var rootNavigation = new LandingNavigationItem(url);
 
+		// Parse x-displayName from OpenAPI tags for user-friendly display names
+		var tagDisplayNames = ParseTagDisplayNames(openApiDocument);
+
 		var ops = openApiDocument.Paths
 			.SelectMany(p => (p.Value.Operations ?? []).Select(op => (Path: p, Operation: op)))
 			.Select(pair =>
@@ -106,9 +110,15 @@ public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocume
 					var apiEndpoint = new ApiEndpoint(operations, apiGroup.Key);
 					apis.Add(apiEndpoint);
 				}
-				var tag = new ApiTag(tagGroup.Key ?? "unknown", "", apis);
+				var tagName = tagGroup.Key ?? "unknown";
+				var displayName = tagDisplayNames.TryGetValue(tagName, out var foundDisplayName) ? foundDisplayName : tagName;
+				var tag = new ApiTag(tagName, displayName, "", apis);
 				tags.Add(tag);
 			}
+
+			// 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);
 		}
@@ -461,4 +471,40 @@ private static string ClassifyElasticsearchTag(string tag)
 		}
 		return "unknown";
 	}
+
+	/// <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.
+	/// </summary>
+	private static Dictionary<string, string> ParseTagDisplayNames(OpenApiDocument openApiDocument)
+	{
+		var displayNames = new Dictionary<string, string>();
+
+		if (openApiDocument.Tags is null)
+			return displayNames;
+
+		foreach (var tag in openApiDocument.Tags)
+		{
+			var tagName = tag.Name;
+			if (string.IsNullOrEmpty(tagName))
+				continue;
+
+			var displayName = tagName; // Default fallback
+
+			// Look for x-displayName extension
+			if (tag.Extensions?.TryGetValue("x-displayName", out var extension) == true &&
+				extension is JsonNodeExtension jsonExtension)
+			{
+				var displayNameValue = jsonExtension.Node.GetValue<string>();
+				if (!string.IsNullOrWhiteSpace(displayNameValue))
+				{
+					displayName = displayNameValue;
+				}
+			}
+
+			displayNames[tagName] = displayName;
+		}
+
+		return displayNames;
+	}
 }