Allow multiple API source to be specified in a single docset

Author: Mpdreamz

docs/_docset.yml

@@ -20,8 +20,9 @@ subs:
 features:
   primary-nav: false
 
-#api: kibana-openapi.json
-api: elasticsearch-openapi.json
+api:
+   elasticsearch: elasticsearch-openapi.json
+   kibana: kibana-openapi.json
 
 toc:
   - file: index.md

src/Elastic.ApiExplorer/OpenApiGenerator.cs

@@ -44,9 +44,9 @@ public class OpenApiGenerator(BuildContext context, IMarkdownStringRenderer mark
 	private readonly IFileSystem _writeFileSystem = context.WriteFileSystem;
 	private readonly StaticFileContentHashProvider _contentHashProvider = new(new EmbeddedOrPhysicalFileProvider(context));
 
-	public LandingNavigationItem CreateNavigation(OpenApiDocument openApiDocument)
+	public LandingNavigationItem CreateNavigation(string apiUrlSuffix, OpenApiDocument openApiDocument)
 	{
-		var url = $"{context.UrlPathPrefix}/api";
+		var url = $"{context.UrlPathPrefix}/api/" + apiUrlSuffix;
 		var rootNavigation = new LandingNavigationItem(url);
 
 		var ops = openApiDocument.Paths
@@ -163,20 +163,21 @@ group tagGroup by classificationGroup.Key
 				var classificationNavigationItem = new ClassificationNavigationItem(classification, rootNavigation, rootNavigation);
 				var tagNavigationItems = new List<IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem>>();
 
-				CreateTagNavigationItems(classification, classificationNavigationItem, classificationNavigationItem, tagNavigationItems);
+				CreateTagNavigationItems(apiUrlSuffix, classification, classificationNavigationItem, classificationNavigationItem, tagNavigationItems);
 				topLevelNavigationItems.Add(classificationNavigationItem);
 				// if there is only a single tag item will be added directly to the classificationNavigationItem, otherwise they will be added to the tagNavigationItems
 				if (classificationNavigationItem.NavigationItems.Count == 0)
 					classificationNavigationItem.NavigationItems = tagNavigationItems;
 			}
 			else
-				CreateTagNavigationItems(classification, rootNavigation, rootNavigation, topLevelNavigationItems);
+				CreateTagNavigationItems(apiUrlSuffix, classification, rootNavigation, rootNavigation, topLevelNavigationItems);
 		}
 		rootNavigation.NavigationItems = topLevelNavigationItems;
 		return rootNavigation;
 	}
 
 	private void CreateTagNavigationItems(
+		string apiUrlSuffix,
 		ApiClassification classification,
 		IRootNavigationItem<IApiGroupingModel, INavigationItem> rootNavigation,
 		IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem> parent,
@@ -190,13 +191,13 @@ List<IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem>> parentNavig
 			if (hasTags)
 			{
 				var tagNavigationItem = new TagNavigationItem(tag, rootNavigation, parent);
-				CreateEndpointNavigationItems(rootNavigation, tag, tagNavigationItem, endpointNavigationItems);
+				CreateEndpointNavigationItems(apiUrlSuffix, rootNavigation, tag, tagNavigationItem, endpointNavigationItems);
 				parentNavigationItems.Add(tagNavigationItem);
 				tagNavigationItem.NavigationItems = endpointNavigationItems;
 			}
 			else
 			{
-				CreateEndpointNavigationItems(rootNavigation, tag, parent, endpointNavigationItems);
+				CreateEndpointNavigationItems(apiUrlSuffix, rootNavigation, tag, parent, endpointNavigationItems);
 				if (parent is ClassificationNavigationItem classificationNavigationItem)
 					classificationNavigationItem.NavigationItems = endpointNavigationItems;
 				else if (parent is LandingNavigationItem landingNavigationItem)
@@ -206,6 +207,7 @@ List<IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem>> parentNavig
 	}
 
 	private void CreateEndpointNavigationItems(
+		string apiUrlSuffix,
 		IRootNavigationItem<IApiGroupingModel, INavigationItem> rootNavigation,
 		ApiTag tag,
 		IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem> parentNavigationItem,
@@ -220,7 +222,7 @@ List<IEndpointOrOperationNavigationItem> endpointNavigationItems
 				var operationNavigationItems = new List<OperationNavigationItem>();
 				foreach (var operation in endpoint.Operations)
 				{
-					var operationNavigationItem = new OperationNavigationItem(context.UrlPathPrefix, operation, rootNavigation, endpointNavigationItem)
+					var operationNavigationItem = new OperationNavigationItem(context.UrlPathPrefix, apiUrlSuffix, operation, rootNavigation, endpointNavigationItem)
 					{
 						Hidden = true
 					};
@@ -232,7 +234,7 @@ List<IEndpointOrOperationNavigationItem> endpointNavigationItems
 			else
 			{
 				var operation = endpoint.Operations.First();
-				var operationNavigationItem = new OperationNavigationItem(context.UrlPathPrefix, operation, rootNavigation, parentNavigationItem);
+				var operationNavigationItem = new OperationNavigationItem(context.UrlPathPrefix, apiUrlSuffix, operation, rootNavigation, parentNavigationItem);
 				endpointNavigationItems.Add(operationNavigationItem);
 
 			}
@@ -241,47 +243,51 @@ List<IEndpointOrOperationNavigationItem> endpointNavigationItems
 
 	public async Task Generate(Cancel ctx = default)
 	{
-		if (context.Configuration.OpenApiSpecification is null)
+		if (context.Configuration.OpenApiSpecifications is null)
 			return;
 
-		var openApiDocument = await OpenApiReader.Create(context.Configuration.OpenApiSpecification);
-		if (openApiDocument is null)
-			return;
-
-		var navigation = CreateNavigation(openApiDocument);
-		_logger.LogInformation("Generating OpenApiDocument {Title}", openApiDocument.Info.Title);
-
-		var navigationRenderer = new IsolatedBuildNavigationHtmlWriter(context, navigation);
+		foreach (var (prefix, path) in context.Configuration.OpenApiSpecifications)
+		{
+			var openApiDocument = await OpenApiReader.Create(path);
+			if (openApiDocument is null)
+				return;
 
+			var navigation = CreateNavigation(prefix, openApiDocument);
+			_logger.LogInformation("Generating OpenApiDocument {Title}", openApiDocument.Info.Title);
 
-		var renderContext = new ApiRenderContext(context, openApiDocument, _contentHashProvider)
-		{
-			NavigationHtml = string.Empty,
-			CurrentNavigation = navigation,
-			MarkdownRenderer = markdownStringRenderer
-		};
-		_ = await Render(navigation, navigation.Index, renderContext, navigationRenderer, ctx);
-		await RenderNavigationItems(navigation);
+			var navigationRenderer = new IsolatedBuildNavigationHtmlWriter(context, navigation);
 
-		async Task RenderNavigationItems(INavigationItem currentNavigation)
-		{
-			if (currentNavigation is INodeNavigationItem<IApiModel, INavigationItem> node)
+			var renderContext = new ApiRenderContext(context, openApiDocument, _contentHashProvider)
 			{
-				_ = await Render(node, node.Index, renderContext, navigationRenderer, ctx);
-				foreach (var child in node.NavigationItems)
-					await RenderNavigationItems(child);
-			}
+				NavigationHtml = string.Empty,
+				CurrentNavigation = navigation,
+				MarkdownRenderer = markdownStringRenderer
+			};
+			_ = await Render(prefix, navigation, navigation.Index, renderContext, navigationRenderer, ctx);
+			await RenderNavigationItems(navigation);
+			async Task RenderNavigationItems(INavigationItem currentNavigation)
+			{
+				if (currentNavigation is INodeNavigationItem<IApiModel, INavigationItem> node)
+				{
+					_ = await Render(prefix, node, node.Index, renderContext, navigationRenderer, ctx);
+					foreach (var child in node.NavigationItems)
+						await RenderNavigationItems(child);
+				}
 
-#pragma warning disable IDE0045
-			else if (currentNavigation is ILeafNavigationItem<IApiModel> leaf)
-#pragma warning restore IDE0045
-				_ = await Render(leaf, leaf.Model, renderContext, navigationRenderer, ctx);
-			else
-				throw new Exception($"Unknown navigation item type {currentNavigation.GetType()}");
+				else
+				{
+					_ = currentNavigation is ILeafNavigationItem<IApiModel> leaf
+						? await Render(prefix, leaf, leaf.Model, renderContext, navigationRenderer, ctx)
+						: throw new Exception($"Unknown navigation item type {currentNavigation.GetType()}");
+				}
+			}
 		}
 	}
 
-	private async Task<IFileInfo> Render<T>(INavigationItem current, T page, ApiRenderContext renderContext, IsolatedBuildNavigationHtmlWriter navigationRenderer, Cancel ctx)
+#pragma warning disable IDE0060
+	private async Task<IFileInfo> Render<T>(string prefix, INavigationItem current, T page, ApiRenderContext renderContext,
+#pragma warning restore IDE0060
+		IsolatedBuildNavigationHtmlWriter navigationRenderer, Cancel ctx)
 		where T : INavigationModel, IPageRenderer<ApiRenderContext>
 	{
 		var outputFile = OutputFile(current);

src/Elastic.ApiExplorer/Operations/OperationNavigationItem.cs

@@ -29,6 +29,7 @@ public class OperationNavigationItem : ILeafNavigationItem<ApiOperation>, IEndpo
 {
 	public OperationNavigationItem(
 		string? urlPathPrefix,
+		string apiUrlSuffix,
 		ApiOperation apiOperation,
 		IRootNavigationItem<IApiGroupingModel, INavigationItem> root,
 		IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem> parent
@@ -39,7 +40,7 @@ IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem> parent
 		NavigationTitle = apiOperation.ApiName;
 		Parent = parent;
 		var moniker = apiOperation.Operation.OperationId ?? apiOperation.Route.Replace("}", "").Replace("{", "").Replace('/', '-');
-		Url = $"{urlPathPrefix}/api/endpoints/{moniker}";
+		Url = $"{urlPathPrefix?.TrimEnd('/')}/api/{apiUrlSuffix}/{moniker}";
 		Id = ShortId.Create(Url);
 	}
 

src/Elastic.ApiExplorer/Operations/OperationView.cshtml

@@ -34,7 +34,7 @@
 			var method = overload.Model.OperationType.ToString().ToLowerInvariant();
 			var current = overload.Model.Route == Model.Operation.Route && overload.Model.OperationType == Model.Operation.OperationType ? "current" : "";
 			<li class="api-url-list-item">
-				<a href="@overload.Url" class="@current">
+				<a href="@overload.Url" class="@current" hx-disable="true">
 					 <span class="api-method api-method-@method">@method.ToUpperInvariant()</span>
 					 <span class="api-url">@overload.Model.Route</span>
 				</a>

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

@@ -50,7 +50,7 @@ public record ConfigurationFile : ITableOfContentsScope
 
 	public IDirectoryInfo ScopeDirectory { get; }
 
-	public IFileInfo? OpenApiSpecification { get; }
+	public IReadOnlyDictionary<string, IFileInfo>? OpenApiSpecifications { get; }
 
 	/// This is a documentation set that is not linked to by assembler.
 	/// Setting this to true relaxes a few restrictions such as mixing toc references with file and folder reference
@@ -111,11 +111,18 @@ public ConfigurationFile(IDocumentationContext context)
 						// read this later
 						break;
 					case "api":
-						var specification = reader.ReadString(entry.Entry);
-						if (specification is null)
+						var configuredApis = reader.ReadDictionary(entry.Entry);
+						if (configuredApis.Count == 0)
 							break;
-						var path = Path.Combine(context.DocumentationSourceDirectory.FullName, specification);
-						OpenApiSpecification = context.ReadFileSystem.FileInfo.New(path);
+
+						var specs = new Dictionary<string, IFileInfo>(StringComparer.OrdinalIgnoreCase);
+						foreach (var (k, v) in configuredApis)
+						{
+							var path = Path.Combine(context.DocumentationSourceDirectory.FullName, v);
+							var fi = context.ReadFileSystem.FileInfo.New(path);
+							specs[k] = fi;
+						}
+						OpenApiSpecifications = specs;
 						break;
 					case "products":
 						if (entry.Entry.Value is not YamlSequenceNode sequence)
@@ -129,7 +136,7 @@ public ConfigurationFile(IDocumentationContext context)
 							YamlScalarNode? productId = null;
 							foreach (var child in node.Children)
 							{
-								if (child.Key is YamlScalarNode { Value: "id" } && child.Value is YamlScalarNode scalarNode)
+								if (child is { Key: YamlScalarNode { Value: "id" }, Value: YamlScalarNode scalarNode })
 								{
 									productId = scalarNode;
 									break;

tests/Elastic.ApiExplorer.Tests/ReaderTests.cs

@@ -35,9 +35,9 @@ public async Task Reads()
 		};
 		var context = new BuildContext(collector, new FileSystem(), versionsConfig);
 
-		context.Configuration.OpenApiSpecification.Should().NotBeNull();
+		context.Configuration.OpenApiSpecifications.Should().NotBeNull().And.NotBeEmpty();
 
-		var x = await OpenApiReader.Create(context.Configuration.OpenApiSpecification);
+		var x = await OpenApiReader.Create(context.Configuration.OpenApiSpecifications.First().Value);
 
 		x.Should().NotBeNull();
 		x.BaseUri.Should().NotBeNull();
@@ -63,11 +63,12 @@ public async Task Navigation()
 		var collector = new DiagnosticsCollector([]);
 		var context = new BuildContext(collector, new FileSystem(), versionsConfig);
 		var generator = new OpenApiGenerator(context, NoopMarkdownStringRenderer.Instance, NullLoggerFactory.Instance);
-		context.Configuration.OpenApiSpecification.Should().NotBeNull();
+		context.Configuration.OpenApiSpecifications.Should().NotBeNull().And.NotBeEmpty();
 
-		var openApiDocument = await OpenApiReader.Create(context.Configuration.OpenApiSpecification);
+		var (urlPathPrefix, fi) = context.Configuration.OpenApiSpecifications.First();
+		var openApiDocument = await OpenApiReader.Create(fi);
 		openApiDocument.Should().NotBeNull();
-		var navigation = generator.CreateNavigation(openApiDocument);
+		var navigation = generator.CreateNavigation(urlPathPrefix, openApiDocument);
 
 		navigation.Should().NotBeNull();
 	}