[API Explorer] Add tag landing pages#3169
Merged
Merged
Conversation
Mpdreamz
approved these changes
Apr 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The API Explorer doesn't currently display all aspects of the OpenAPI tag object.
This PR adds automatically-generated tag landing pages for API Explorer so each OpenAPI tag can show the
descriptionandexternalDocs.Each landing page also has an operations table (same as on API landing page, but filtered to the relevant tag), though if folks don't like this I am fine with removing that content).
If an OpenAPI document has x-tagGroups, those are unchanged (i.e. I have not added landing pages for tag groups at this time since there's no additional
descriptionorexternalDocsat that level). Relates to #3166Screenshots
Kibana example:
Elasticsearch example:
Reviewer notes
Note that I manually edited the
kibana-openapi.jsonfile to remove some URLs with old relative paths in the tag descriptions, since they caused docs-builder errors.Implentation details
Data model & parsing (
OpenApiGenerator.cs)ApiTagExternalDoc:Description+Urlfor tag-levelexternalDocs.ApiTag: extended withDescription,ExternalDocs, andTagUrlSegment(canonical moniker for URLs), plus existingName,DisplayName,Endpoints.ParseOpenApiTagMetadata: reads globaltags[]from the OpenAPI document fordescription,externalDocs, andx-displayName(display name fallback to canonicalname).GenerateTagMoniker: normalizes canonical tagnameinto a single URL segment (trim, collapse spaces, strip{/},/→-, spaces →-, empty →unknown).BuildTagMonikerMap: fails the build if two different tag names normalize to the same segment (clear error naming both tags and the segment).Navigation & URLs (
LandingNavigationItem.cs)TagNavigationItem.Url:.../api/{apiUrlSuffix}/tags/{tag.TagUrlSegment}/(dedicated tag landing route, not the first operation URL).Rendering
ApiTag.RenderAsync: buildsTagLandingViewModel, rendersTagLandingViewvia RazorSlices (TagLandingView.Create), streaming to the output file (aligned with other API Explorer Razor pages).TagLandingViewModel: extendsApiViewModel,Tag, layout title fromTag.DisplayName.TagLandingView.cshtml: H1 + optional canonical name line; CommonMark description via existing markdown pipeline;externalDocslink with elastic.co/docs same-tab vstarget="_blank"+relfor other hosts; operations table mirroring main landing patterns (endpoints with overloads vs single operations).Main API overview (
LandingView.cshtml)TagNavigationItem.Url(tag landing) with a dedicated class for styling.Dependencies
Elastic.ApiExplorer.csproj:RazorSlicespackage reference for tag page rendering.Tests (
tests/Elastic.ApiExplorer.Tests/TagMetadataTests.cs)Embedded small OpenAPI JSON fixtures (not the full
elasticsearch-openapi.json), including:Single_Tag_Still_Creates_TagNavigationItem: single-tag specs still get a tag level in the tree.GenerateTagMoniker_DataStream_Uses_Hyphen: space in tag name →data-stream-style segment.Tag_Url_Uses_Tags_Segment: URLs use the/tags/path.Tag_Landing_Parses_Description_And_ExternalDocs_Like_Elasticsearch_Connector_Tag: connector-style metadata.CreateNavigation_Throws_When_Two_Tag_Names_Normalize_To_Same_Url_Segment: moniker collision failure.User documentation (
docs/configure/content-set/api-explorer.md)Mention:
description(CommonMark, Mustache escaping consistent with other API pages),externalDocslink behavior.tasks,data stream→data-stream,ccr), collision error, reservedtagssegment vs intro/outro slugs.Generative AI disclosure
Tool(s) and model(s) used: composer-2