Merge remote-tracking branch 'origin/main' into feature/private_bundling

Author: cotti

Directory.Packages.props

@@ -26,18 +26,18 @@
   <ItemGroup>
     <PackageVersion Include="Amazon.Lambda.APIGatewayEvents" Version="2.7.1" />
     <PackageVersion Include="Amazon.Lambda.AspNetCoreServer.Hosting" Version="1.9.0" />
-    <PackageVersion Include="Amazon.Lambda.RuntimeSupport" Version="1.14.2" />
+    <PackageVersion Include="Amazon.Lambda.RuntimeSupport" Version="1.14.3" />
     <PackageVersion Include="Amazon.Lambda.Core" Version="2.8.1" />
     <PackageVersion Include="Amazon.Lambda.S3Events" Version="3.1.2" />
     <PackageVersion Include="Amazon.Lambda.Serialization.SystemTextJson" Version="2.4.5" />
     <PackageVersion Include="Amazon.Lambda.SQSEvents" Version="2.2.1" />
     <PackageVersion Include="AngleSharp" Version="1.4.0" />
     <PackageVersion Include="Aspire.Hosting" Version="13.0.0" />
     <PackageVersion Include="Aspire.Hosting.Testing" Version="13.0.0" />
-    <PackageVersion Include="AWSSDK.Core" Version="4.0.3.29" />
-    <PackageVersion Include="AWSSDK.DynamoDBv2" Version="4.0.14.1" />
+    <PackageVersion Include="AWSSDK.Core" Version="4.0.3.30" />
+    <PackageVersion Include="AWSSDK.DynamoDBv2" Version="4.0.17.9" />
     <PackageVersion Include="AWSSDK.SQS" Version="4.0.2.25" />
-    <PackageVersion Include="AWSSDK.S3" Version="4.0.18.6" />
+    <PackageVersion Include="AWSSDK.S3" Version="4.0.21.2" />
     <PackageVersion Include="Elastic.OpenTelemetry" Version="1.1.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.3" />

config/versions.yml

@@ -91,7 +91,7 @@ versioning_systems:
     current: 1.10.0
   edot-node:
     base: 1.0
-    current: 1.10.0
+    current: 1.11.0
   edot-php:
     base: 1.0
     current: 1.3.1
@@ -102,7 +102,7 @@ versioning_systems:
     base: 1.0
     current: 1.5.0
   edot-cf-azure:
-    base: 0.1
+    base: 0.7.1
     current: 0.7.1
   edot-cf-gcp:
     base: 0.1

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)

docs/syntax/automated_settings.md

@@ -73,6 +73,7 @@ It demonstrates:
 - `note`, `tip`, `warning`, `important`, and `deprecation_details`.
 - Nested `settings`.
 - `applies_to` inheritance and override behavior.
+- Inline `{applies_to}` badges inside a setting `description` (for example, to label per-version defaults in a bulleted list).
 - Top-level `page_description`.
 
 ### Result

docs/syntax/settings-with-applies-example.yml

@@ -54,6 +54,15 @@ groups:
           xpack.example.mode: strict
           ```
 
+      - setting: xpack.example.defaultModel
+        id: xpack-example-default-model
+        description: |
+          Default model used by the feature. The default varies by version:
+
+          * {applies_to}`stack: ga 9.2` Defaults to `model-v2`.
+          * {applies_to}`stack: ga 9.1` Defaults to `model-v1`.
+        datatype: string
+
   - group: Advanced settings
     id: advanced-settings
     description: |

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;
+	}
 }