[API Explorer] Basic customized landing pages (#3121)

Author: lcawl

docs/_docset.yml

@@ -8,6 +8,8 @@ cross_links:
 exclude:
   - '_*.md'
   - '!_search.md'
+  # API landing templates (see api.*.template): not standalone TOC pages; including them causes "Could not find … in navigation" during serve/build.
+  - '*-api-overview.md'
 subs:
   a-global-variable: "This was defined in docset.yml"
   serverless-short: Serverless
@@ -48,7 +50,9 @@ suppress:
 
 api:
    elasticsearch: elasticsearch-openapi.json
-   kibana: kibana-openapi.json
+   kibana:
+     spec: kibana-openapi.json
+     template: kibana-api-overview.md
    dashboard: dashboard-openapi.json
 
 toc:

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

@@ -12,7 +12,10 @@ This feature is still under development and the functionality described on this
 
 ## Configure the API Explorer
 
-Add the `api` key to your `docset.yml` file to enable the API Explorer. The key maps product names to OpenAPI JSON specification files. Paths are relative to the folder that contains `docset.yml`.
+Add the `api` key to your `docset.yml` file to enable the API Explorer. The key maps product names to OpenAPI JSON specification files.
+Paths are relative to the folder that contains `docset.yml`.
+
+### Basic Configuration
 
 ```yaml
 api:
@@ -24,6 +27,39 @@ Each product key produces its own section of API documentation. For example, `el
 
 The `api` key is only valid in `docset.yml`. You can't use it in `toc.yml` files.
 
+### Advanced configuration with templates
+
+When you specify a `template` file, `docs-builder` uses your custom Markdown file as the API landing page instead of generating an automatic overview:
+
+```yaml
+api:
+  kibana:
+    spec: kibana-openapi.json
+    template: kibana-api-overview.md
+```
+
+Template files:
+
+- Must be Markdown files with `.md` extension
+- Can use standard Markdown, substitutions
+
+:::{note}
+They must be explicitly excluded if they are not used in your table of contents.
+Otherwise `docs-builder` treats them like normal pages and navigation can fail at build or serve time.
+Add a glob (or explicit paths) under `exclude:` in `docset.yml` that matches your template filenames.
+For example, exclude `*-api-overview.md`.
+:::
+
+#### Template example
+
+Here's a sample template file (`kibana-api-overview.md`):
+
+```markdown
+# Kibana APIs
+
+Welcome to the Kibana API documentation.
+```
+
 ## Place your spec files
 
 OpenAPI specification files must be in JSON format and located in the same folder as your `docset.yml` (or in a subfolder of it). The path you specify in `api` is resolved relative to the `docset.yml` location.

docs/kibana-api-overview.md

@@ -0,0 +1,20 @@
+# Kibana APIs
+
+Welcome to the Kibana API documentation. This page provides an overview of the available Kibana APIs.
+
+## Kibana spaces
+
+Spaces enable you to organize your dashboards and other saved objects into meaningful categories.
+You can use the default space or create your own spaces.
+
+To run APIs in non-default spaces, you must add `s/{space_id}/` to the path.
+For example:
+
+```bash
+curl -X GET "http://${KIBANA_URL}/s/marketing/api/data_views" \
+-H "Authorization: ApiKey ${API_KEY}"
+```
+
+If you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.
+
+To learn more, check out [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces).

src/Elastic.ApiExplorer/ApiRenderContext.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 Elastic.ApiExplorer.Landing;
 using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Navigation;
@@ -21,4 +22,7 @@ StaticFileContentHashProvider StaticFileContentHashProvider
 	public required string NavigationHtml { get; init; }
 	public required INavigationItem CurrentNavigation { get; init; }
 	public required IMarkdownStringRenderer MarkdownRenderer { get; init; }
+
+	/// <summary>When set, the API root index uses this model instead of <see cref="Landing.ApiLanding"/>.</summary>
+	public TemplateLanding? TemplateLandingPage { get; init; }
 }

src/Elastic.ApiExplorer/ApiViewModel.cs

@@ -25,12 +25,12 @@ public record ApiLayoutViewModel : GlobalLayoutViewModel
 
 public abstract partial class ApiViewModel(ApiRenderContext context)
 {
-	public string NavigationHtml { get; } = context.NavigationHtml;
-	public StaticFileContentHashProvider StaticFileContentHashProvider { get; } = context.StaticFileContentHashProvider;
-	public INavigationItem CurrentNavigationItem { get; } = context.CurrentNavigation;
-	public IMarkdownStringRenderer MarkdownRenderer { get; } = context.MarkdownRenderer;
-	public BuildContext BuildContext { get; } = context.BuildContext;
-	public OpenApiDocument Document { get; } = context.Model;
+	public string NavigationHtml { get; } = context?.NavigationHtml ?? string.Empty;
+	public StaticFileContentHashProvider StaticFileContentHashProvider { get; } = context?.StaticFileContentHashProvider ?? throw new ArgumentNullException(nameof(context), "StaticFileContentHashProvider cannot be null");
+	public INavigationItem CurrentNavigationItem { get; } = context?.CurrentNavigation ?? throw new ArgumentNullException(nameof(context), "CurrentNavigation cannot be null");
+	public IMarkdownStringRenderer MarkdownRenderer { get; } = context?.MarkdownRenderer ?? throw new ArgumentNullException(nameof(context), "MarkdownRenderer cannot be null");
+	public BuildContext BuildContext { get; } = context?.BuildContext ?? throw new ArgumentNullException(nameof(context), "BuildContext cannot be null");
+	public OpenApiDocument Document { get; } = context?.Model ?? throw new ArgumentNullException(nameof(context), "OpenApiDocument cannot be null");
 
 
 	public HtmlString RenderMarkdown(string? markdown)
@@ -81,8 +81,8 @@ public ApiLayoutViewModel CreateGlobalLayoutModel()
 			BuildType = BuildContext.BuildType,
 			TocItems = GetTocItems(),
 			// Header properties for isolated mode
-			HeaderTitle = Document.Info.Title,
-			HeaderVersion = Document.Info.Version,
+			HeaderTitle = Document.Info?.Title ?? "API Documentation",
+			HeaderVersion = Document.Info?.Version ?? "1.0",
 			GitBranch = BuildContext.Git.Branch != "unavailable" ? BuildContext.Git.Branch : null,
 			GitCommitShort = BuildContext.Git.Ref is { Length: >= 7 } r && r != "unavailable" ? r[..7] : null,
 			GitRepository = BuildContext.Git.RepositoryName != "unavailable" ? BuildContext.Git.RepositoryName : null,

src/Elastic.ApiExplorer/Landing/TemplateLanding.cs

@@ -0,0 +1,39 @@
+// 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 Elastic.Documentation.Extensions;
+using Microsoft.OpenApi;
+using RazorSlices;
+
+namespace Elastic.ApiExplorer.Landing;
+
+/// <summary>
+/// Template-based API landing page model.
+/// </summary>
+public class TemplateLanding(string templateContent) : IApiGroupingModel
+{
+	/// <summary>
+	/// The processed template content as HTML.
+	/// </summary>
+	public string TemplateContent { get; } = templateContent;
+
+	/// <summary>
+	/// Renders the template-based landing page.
+	/// </summary>
+	public async Task RenderAsync(FileSystemStream stream, ApiRenderContext context, Cancel ctx = default)
+	{
+		if (context?.Model == null)
+			throw new ArgumentNullException(nameof(context), "Context or context.Model cannot be null");
+
+		var viewModel = new TemplateLandingViewModel(context)
+		{
+			Landing = this,
+			TemplateContent = TemplateContent,
+			ApiInfo = context.Model.Info ?? new() { Title = "API Documentation", Version = "1.0" }
+		};
+		var slice = TemplateLandingView.Create(viewModel);
+		await slice.RenderAsync(stream, cancellationToken: ctx);
+	}
+}

src/Elastic.ApiExplorer/Landing/TemplateLandingView.cshtml

@@ -0,0 +1,21 @@
+@inherits RazorSliceHttpResult<Elastic.ApiExplorer.Landing.TemplateLandingViewModel>
+@using Elastic.ApiExplorer.Landing
+@using Elastic.Documentation.Navigation
+@using Elastic.Documentation.Site.Navigation
+@using Microsoft.AspNetCore.Html
+@implements IUsesLayout<Elastic.ApiExplorer._Layout, ApiLayoutViewModel>
+@functions {
+	public ApiLayoutViewModel LayoutModel => Model.CreateGlobalLayoutModel();
+}
+
+<section id="elastic-docs-v3">
+	@if (!string.IsNullOrEmpty(Model.TemplateContent))
+	{
+		@(new HtmlString(Model.TemplateContent))
+	}
+	else
+	{
+		<h1>API Documentation</h1>
+		<p>Welcome to the API documentation.</p>
+	}
+</section>

src/Elastic.ApiExplorer/Landing/TemplateLandingViewModel.cs

@@ -0,0 +1,28 @@
+// 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 Microsoft.OpenApi;
+
+namespace Elastic.ApiExplorer.Landing;
+
+/// <summary>
+/// View model for template-based API landing pages.
+/// </summary>
+public class TemplateLandingViewModel(ApiRenderContext context) : ApiViewModel(context)
+{
+	/// <summary>
+	/// The template landing model.
+	/// </summary>
+	public required TemplateLanding Landing { get; init; }
+
+	/// <summary>
+	/// The processed template content as HTML.
+	/// </summary>
+	public required string TemplateContent { get; init; }
+
+	/// <summary>
+	/// The API information from the OpenAPI specification.
+	/// </summary>
+	public required OpenApiInfo ApiInfo { get; init; }
+}

src/Elastic.ApiExplorer/OpenApiGenerator.cs

@@ -7,8 +7,10 @@
 using Elastic.ApiExplorer.Landing;
 using Elastic.ApiExplorer.Operations;
 using Elastic.ApiExplorer.Schemas;
+using Elastic.ApiExplorer.Templates;
 using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
+using Elastic.Documentation.Configuration.Toc;
 using Elastic.Documentation.Navigation;
 using Elastic.Documentation.Site.FileProviders;
 using Elastic.Documentation.Site.Navigation;
@@ -44,6 +46,7 @@ public class OpenApiGenerator(ILoggerFactory logFactory, BuildContext context, I
 	private readonly ILogger _logger = logFactory.CreateLogger<OpenApiGenerator>();
 	private readonly IFileSystem _writeFileSystem = context.WriteFileSystem;
 	private readonly StaticFileContentHashProvider _contentHashProvider = new(new EmbeddedOrPhysicalFileProvider(context));
+	private readonly TemplateProcessor _templateProcessor = TemplateProcessorFactory.Create(markdownStringRenderer, context.ReadFileSystem);
 
 	public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocument openApiDocument)
 	{
@@ -208,41 +211,79 @@ List<IEndpointOrOperationNavigationItem> endpointNavigationItems
 
 	public async Task Generate(Cancel ctx = default)
 	{
-		if (context.Configuration.OpenApiSpecifications is null)
-			return;
+		// Use the new API configurations if available, otherwise fall back to legacy OpenApiSpecifications
+		if (context.Configuration.ApiConfigurations is not null)
+		{
+			foreach (var (prefix, apiConfig) in context.Configuration.ApiConfigurations)
+			{
+				// Validate assumption of single spec per product
+				if (apiConfig.SpecFiles.Count > 1)
+					throw new InvalidOperationException($"API product '{prefix}' has {apiConfig.SpecFiles.Count} spec files, but only one spec file per product is currently supported.");
 
-		foreach (var (prefix, path) in context.Configuration.OpenApiSpecifications)
+				var openApiDocument = await OpenApiReader.Create(apiConfig.PrimarySpecFile);
+				if (openApiDocument is null)
+					continue;
+
+				await GenerateApiProduct(prefix, openApiDocument, apiConfig, ctx);
+			}
+		}
+		else if (context.Configuration.OpenApiSpecifications is not null)
 		{
-			var openApiDocument = await OpenApiReader.Create(path);
-			if (openApiDocument is null)
-				return;
+			// Legacy fallback
+			foreach (var (prefix, path) in context.Configuration.OpenApiSpecifications)
+			{
+				var openApiDocument = await OpenApiReader.Create(path);
+				if (openApiDocument is null)
+					continue;
 
-			var navigation = CreateNavigation(prefix, openApiDocument);
-			_logger.LogInformation("Generating OpenApiDocument {Title}", openApiDocument.Info.Title);
+				await GenerateApiProduct(prefix, openApiDocument, null, ctx);
+			}
+		}
+	}
 
-			var navigationRenderer = new IsolatedBuildNavigationHtmlWriter(context, navigation);
+	private async Task GenerateApiProduct(string prefix, OpenApiDocument openApiDocument, ResolvedApiConfiguration? apiConfig, Cancel ctx)
+	{
+		var navigation = CreateNavigation(prefix, openApiDocument);
+		_logger.LogInformation("Generating OpenApiDocument {Title}", openApiDocument.Info?.Title ?? "<no title>");
 
-			var renderContext = new ApiRenderContext(context, openApiDocument, _contentHashProvider)
-			{
-				NavigationHtml = string.Empty,
-				CurrentNavigation = navigation,
-				MarkdownRenderer = markdownStringRenderer
-			};
-			_ = await Render(prefix, navigation, navigation.Index.Model, renderContext, navigationRenderer, ctx);
-			await RenderNavigationItems(prefix, renderContext, navigationRenderer, navigation, ctx);
+		var navigationRenderer = new IsolatedBuildNavigationHtmlWriter(context, navigation);
 
+		TemplateLanding? templateLanding = null;
+		if (apiConfig?.HasCustomTemplate == true)
+		{
+			var templateContent = await _templateProcessor.ProcessTemplateAsync(apiConfig, ctx);
+			if (!string.IsNullOrWhiteSpace(templateContent))
+				templateLanding = new TemplateLanding(templateContent);
 		}
+
+		var renderContext = new ApiRenderContext(context, openApiDocument, _contentHashProvider)
+		{
+			NavigationHtml = string.Empty,
+			CurrentNavigation = navigation,
+			MarkdownRenderer = markdownStringRenderer,
+			TemplateLandingPage = templateLanding
+		};
+
+		await RenderNavigationItems(prefix, renderContext, navigationRenderer, navigation, navigation, ctx);
 	}
 
-	private async Task RenderNavigationItems(string prefix, ApiRenderContext renderContext, IsolatedBuildNavigationHtmlWriter navigationRenderer, INavigationItem currentNavigation, Cancel ctx)
+	private async Task RenderNavigationItems(
+		string prefix,
+		ApiRenderContext renderContext,
+		IsolatedBuildNavigationHtmlWriter navigationRenderer,
+		INavigationItem currentNavigation,
+		INavigationItem rootNavigation,
+		Cancel ctx)
 	{
 		if (currentNavigation is INodeNavigationItem<IApiModel, INavigationItem> node)
 		{
-			_ = await Render(prefix, node, node.Index.Model, renderContext, navigationRenderer, ctx);
+			_ = renderContext.TemplateLandingPage is { } templateLanding && ReferenceEquals(currentNavigation, rootNavigation)
+				? await Render(prefix, node, templateLanding, renderContext, navigationRenderer, ctx)
+				: await Render(prefix, node, node.Index.Model, renderContext, navigationRenderer, ctx);
+
 			foreach (var child in node.NavigationItems)
-				await RenderNavigationItems(prefix, renderContext, navigationRenderer, child, ctx);
+				await RenderNavigationItems(prefix, renderContext, navigationRenderer, child, rootNavigation, ctx);
 		}
-
 		else
 		{
 			_ = currentNavigation is ILeafNavigationItem<IApiModel> leaf