[API Explorer] Landing page setup (#3120)

Author: lcawl

src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs

@@ -58,6 +58,11 @@ public record ConfigurationFile
 
 	public IReadOnlyDictionary<string, IFileInfo>? OpenApiSpecifications { get; }
 
+	/// <summary>
+	/// Resolved API configurations with template and specification file information.
+	/// </summary>
+	public IReadOnlyDictionary<string, ResolvedApiConfiguration>? ApiConfigurations { get; }
+
 	/// <summary>
 	/// Set of diagnostic hint types to suppress for this documentation set.
 	/// </summary>
@@ -134,17 +139,81 @@ public ConfigurationFile(DocumentationSetFile docSetFile, IDocumentationSetConte
 			// Read substitutions
 			_substitutions = new(docSetFile.Subs, StringComparer.OrdinalIgnoreCase);
 
-			// Process API specifications
+			// Process API configurations
 			if (docSetFile.Api.Count > 0)
 			{
 				var specs = new Dictionary<string, IFileInfo>(StringComparer.OrdinalIgnoreCase);
-				foreach (var (k, v) in docSetFile.Api)
+				var apiConfigs = new Dictionary<string, ResolvedApiConfiguration>(StringComparer.OrdinalIgnoreCase);
+
+				foreach (var (productKey, apiConfig) in docSetFile.Api)
 				{
-					var path = Path.Join(context.DocumentationSourceDirectory.FullName, v);
-					var fi = context.ReadFileSystem.FileInfo.New(path);
-					specs[k] = fi;
+					if (!apiConfig.IsValid)
+					{
+						context.EmitError(
+							context.ConfigurationPath,
+							$"API configuration for '{productKey}' is invalid. Must have at least one spec and cannot specify both 'spec' and 'specs'."
+						);
+						continue;
+					}
+
+					// Resolve template file if specified
+					IFileInfo? templateFile = null;
+					if (!string.IsNullOrEmpty(apiConfig.Template))
+					{
+						var templatePath = Path.Join(context.DocumentationSourceDirectory.FullName, apiConfig.Template);
+						templateFile = context.ReadFileSystem.FileInfo.New(templatePath);
+						if (!templateFile.Exists)
+						{
+							context.EmitWarning(
+								context.ConfigurationPath,
+								$"Template file '{apiConfig.Template}' for API '{productKey}' does not exist."
+							);
+							templateFile = null;
+						}
+					}
+
+					// Resolve specification files
+					var specFiles = new List<IFileInfo>();
+					foreach (var specPath in apiConfig.GetSpecPaths())
+					{
+						var fullPath = Path.Join(context.DocumentationSourceDirectory.FullName, specPath);
+						var specFile = context.ReadFileSystem.FileInfo.New(fullPath);
+						if (!specFile.Exists)
+						{
+							context.EmitError(
+								context.ConfigurationPath,
+								$"API specification file '{specPath}' for product '{productKey}' does not exist."
+							);
+							continue;
+						}
+						specFiles.Add(specFile);
+					}
+
+					if (specFiles.Count == 0)
+					{
+						context.EmitError(
+							context.ConfigurationPath,
+							$"No valid specification files found for API product '{productKey}'."
+						);
+						continue;
+					}
+
+					// Create resolved configuration
+					var resolvedConfig = new ResolvedApiConfiguration
+					{
+						ProductKey = productKey,
+						TemplateFile = templateFile,
+						SpecFiles = specFiles
+					};
+
+					apiConfigs[productKey] = resolvedConfig;
+
+					// For backward compatibility, populate OpenApiSpecifications with primary spec
+					specs[productKey] = resolvedConfig.PrimarySpecFile;
 				}
-				OpenApiSpecifications = specs;
+
+				OpenApiSpecifications = specs.Count > 0 ? specs : null;
+				ApiConfigurations = apiConfigs.Count > 0 ? apiConfigs : null;
 			}
 
 			// Process products from docset - resolve ProductLinks to Product objects

src/Elastic.Documentation.Configuration/ConfigurationFileProvider.cs

@@ -28,6 +28,7 @@ public partial class ConfigurationFileProvider
 		.WithTypeConverter(new TocItemYamlConverter())
 		.WithTypeConverter(new SiteTableOfContentsCollectionYamlConverter())
 		.WithTypeConverter(new SiteTableOfContentsRefYamlConverter())
+		.WithTypeConverter(new ApiConfigurationConverter())
 		.Build();
 
 	public ConfigurationSource ConfigurationSource { get; }

src/Elastic.Documentation.Configuration/Toc/ApiConfiguration.cs

@@ -0,0 +1,78 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// 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.IO.Abstractions;
+using YamlDotNet.Serialization;
+
+namespace Elastic.Documentation.Configuration.Toc;
+
+/// <summary>
+/// Configuration for API documentation generation from OpenAPI specifications.
+/// </summary>
+[YamlSerializable]
+public class ApiConfiguration
+{
+	/// <summary>
+	/// Path to a single OpenAPI specification file (for backward compatibility).
+	/// Cannot be used together with <see cref="Specs"/>.
+	/// </summary>
+	[YamlMember(Alias = "spec")]
+	public string? Spec { get; set; }
+
+	/// <summary>
+	/// Paths to multiple OpenAPI specification files (future feature).
+	/// Cannot be used together with <see cref="Spec"/>.
+	/// </summary>
+	[YamlMember(Alias = "specs")]
+	public List<string>? Specs { get; set; }
+
+	/// <summary>
+	/// Path to a Markdown template file to use as the API landing page.
+	/// If not specified, an auto-generated landing page will be used.
+	/// </summary>
+	[YamlMember(Alias = "template")]
+	public string? Template { get; set; }
+
+	/// <summary>
+	/// Validates that the configuration is valid.
+	/// Must have a non-empty spec path. Multi-spec support is deferred to future implementation.
+	/// </summary>
+	public bool IsValid =>
+		!string.IsNullOrWhiteSpace(Spec);
+
+	/// <summary>
+	/// Gets all specification file paths, handling both single spec and multi-spec configurations.
+	/// </summary>
+	public IEnumerable<string> GetSpecPaths()
+	{
+		if (Spec != null)
+			yield return Spec;
+
+		if (Specs?.Count > 0)
+		{
+			foreach (var spec in Specs)
+				yield return spec;
+		}
+	}
+}
+
+/// <summary>
+/// Resolved API configuration with validated file references.
+/// </summary>
+public class ResolvedApiConfiguration
+{
+	public required string ProductKey { get; init; }
+	public IFileInfo? TemplateFile { get; init; }
+	public required List<IFileInfo> SpecFiles { get; init; }
+
+	/// <summary>
+	/// Whether this configuration has a custom template file.
+	/// </summary>
+	public bool HasCustomTemplate => TemplateFile != null;
+
+	/// <summary>
+	/// Primary specification file (first in the list, for backward compatibility).
+	/// </summary>
+	public IFileInfo PrimarySpecFile => SpecFiles.First();
+}

src/Elastic.Documentation.Configuration/Toc/ApiConfigurationConverter.cs

@@ -0,0 +1,90 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// 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 YamlDotNet.Core;
+using YamlDotNet.Core.Events;
+using YamlDotNet.Serialization;
+using static YamlDotNet.Core.ParserExtensions;
+
+namespace Elastic.Documentation.Configuration.Toc;
+
+/// <summary>
+/// YAML converter that provides backward compatibility for API configuration.
+/// Supports both old string format and new object format.
+/// 
+/// Old format: api: { elasticsearch: "elasticsearch-openapi.json" }
+/// New format: api: { elasticsearch: { spec: "elasticsearch-openapi.json", template: "elasticsearch-api-overview.md" } }
+/// </summary>
+public class ApiConfigurationConverter : IYamlTypeConverter
+{
+	public bool Accepts(Type type) => type == typeof(ApiConfiguration);
+
+	public object? ReadYaml(IParser parser, Type type, ObjectDeserializer rootDeserializer)
+	{
+		if (parser.Current is Scalar scalar)
+		{
+			// Handle old string format: "elasticsearch-openapi.json"
+			_ = parser.MoveNext();
+			return new ApiConfiguration { Spec = scalar.Value };
+		}
+
+		if (parser.Current is MappingStart)
+		{
+			// Handle new object format: { spec: "...", template: "...", specs: [...] }
+			_ = parser.MoveNext();
+			var config = new ApiConfiguration();
+
+			while (parser.Current is not MappingEnd)
+			{
+				var key = parser.Consume<Scalar>();
+				switch (key.Value)
+				{
+					case "spec":
+						if (parser.Current is Scalar specValue)
+						{
+							config.Spec = specValue.Value;
+							_ = parser.MoveNext();
+						}
+						else
+						{
+							// Wrong token type - skip safely
+							parser.SkipThisAndNestedEvents();
+						}
+						break;
+					case "template":
+						if (parser.Current is Scalar templateValue)
+						{
+							config.Template = templateValue.Value;
+							_ = parser.MoveNext();
+						}
+						else
+						{
+							// Wrong token type - skip safely
+							parser.SkipThisAndNestedEvents();
+						}
+						break;
+					default:
+						// Safely consume unknown values (including nested mappings/sequences)
+						parser.SkipThisAndNestedEvents();
+						break;
+				}
+			}
+
+			_ = parser.MoveNext(); // consume MappingEnd
+			return config;
+		}
+
+		throw new YamlException(parser.Current?.Start ?? Mark.Empty, parser.Current?.End ?? Mark.Empty,
+			"API configuration must be either a string (spec path) or an object with spec/template fields");
+	}
+
+	public void WriteYaml(IEmitter emitter, object? value, Type type, ObjectSerializer serializer)
+	{
+		if (value is ApiConfiguration config)
+		{
+			// Always write as object format for consistency
+			serializer(config, typeof(ApiConfiguration));
+		}
+	}
+}

src/Elastic.Documentation.Configuration/Toc/DocumentationSetFile.cs

@@ -52,7 +52,7 @@ public class DocumentationSetFile : TableOfContentsFile
 	public DocumentationSetFeatures Features { get; set; } = new();
 
 	[YamlMember(Alias = "api")]
-	public Dictionary<string, string> Api { get; set; } = [];
+	public Dictionary<string, ApiConfiguration> Api { get; set; } = [];
 
 	/// <summary>
 	/// Default products for this documentation set. These are merged with page-level frontmatter products.