Skip to content

[API Explorer] Add tag landing pages#3169

Merged
lcawl merged 3 commits into
api-explorer-improvementsfrom
tag-descriptions
Apr 23, 2026
Merged

[API Explorer] Add tag landing pages#3169
lcawl merged 3 commits into
api-explorer-improvementsfrom
tag-descriptions

Conversation

@lcawl
Copy link
Copy Markdown
Contributor

@lcawl lcawl commented Apr 22, 2026

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 description and externalDocs.
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 description or externalDocs at that level). Relates to #3166

Screenshots

Kibana example:

image

Elasticsearch example:

image

Reviewer notes

Note that I manually edited the kibana-openapi.json file 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 + Url for tag-level externalDocs.
  • ApiTag: extended with Description, ExternalDocs, and TagUrlSegment (canonical moniker for URLs), plus existing Name, DisplayName, Endpoints.
  • ParseOpenApiTagMetadata: reads global tags[] from the OpenAPI document for description, externalDocs, and x-displayName (display name fallback to canonical name).
  • GenerateTagMoniker: normalizes canonical tag name into 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: builds TagLandingViewModel, renders TagLandingView via RazorSlices (TagLandingView.Create), streaming to the output file (aligned with other API Explorer Razor pages).
  • TagLandingViewModel: extends ApiViewModel, Tag, layout title from Tag.DisplayName.
  • TagLandingView.cshtml: H1 + optional canonical name line; CommonMark description via existing markdown pipeline; externalDocs link with elastic.co/docs same-tab vs target="_blank" + rel for other hosts; operations table mirroring main landing patterns (endpoints with overloads vs single operations).

Main API overview (LandingView.cshtml)

  • Tag rows link to TagNavigationItem.Url (tag landing) with a dedicated class for styling.

Dependencies

  • Elastic.ApiExplorer.csproj: RazorSlices package reference for tag page rendering.

Tests (tests/Elastic.ApiExplorer.Tests/TagMetadataTests.cs)

Embedded small OpenAPI JSON fixtures (not the full elasticsearch-openapi.json), including:

  • Display name / canonical name / sorting behavior where relevant.
  • 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:

  • Tag landing pages: description (CommonMark, Mustache escaping consistent with other API pages), externalDocs link behavior.
  • Tag landing URLs: path shape, segment rules, examples (tasks, data streamdata-stream, ccr), collision error, reserved tags segment vs intro/outro slugs.

Generative AI disclosure

  1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?
  • Yes
  • No
  1. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-2

@lcawl lcawl marked this pull request as ready for review April 22, 2026 22:11
@lcawl lcawl requested review from a team as code owners April 22, 2026 22:11
@lcawl lcawl requested review from szabosteve and technige April 22, 2026 22:11
@lcawl lcawl merged commit deec14f into api-explorer-improvements Apr 23, 2026
23 checks passed
@lcawl lcawl deleted the tag-descriptions branch April 23, 2026 16:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants