Merge API explorer improvements

docs/_docset.yml

@@ -1,4 +1,4 @@
 project: 'doc-builder'
 max_toc_depth: 2
 # indicates this documentation set is not linkable by assembler.
 # relaxes a few restrictions around toc building and file placement
@@ -50,7 +50,7 @@
   - DeepLinkingVirtualFile
 
 api:
-   elasticsearch: elasticsearch-openapi.json
+   elasticsearch: elasticsearch-openapi-docs.json
    kibana:
      - file: kibana-api-overview.md
      - spec: kibana-openapi.json

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

@@ -15,7 +15,7 @@ This feature is still under development and the functionality described on this
 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
+### Basic configuration
 
 ```yaml
 api:
@@ -83,6 +83,10 @@ Make sure you have:
 - Understanding of RESTful API principles
 ```
 
+:::{important}
+Intro and outro Markdown files must not use a slug that would collide with the reserved API Explorer segments like `types` and `tags`.
+:::
+
 ## 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.
@@ -133,14 +137,66 @@ toc:
 The API Explorer generates the following types of pages from your OpenAPI spec:
 
 - **Landing page**: An overview of the API grouped by tag
+- **Tag landing pages**: One page per tag that lists operations in that tag, with the tag's display name, optional OpenAPI `description` (CommonMark), and optional `externalDocs` link
 - **Operation pages**: One page per API operation, with the HTTP method, path, parameters, request body, response schemas, and examples
 - **Schema type pages**: Dedicated pages for complex shared types such as `QueryContainer` and `AggregationContainer`
 
 ## OpenAPI extensions
 
-The API Explorer supports the following OpenAPI specification extensions to enhance navigation and display:
+The API Explorer supports some OpenAPI specification extensions to enhance navigation and display:
+
+- [x-codeSamples](#x-codesamples)
+- [x-displayName](#x-displayname)
+- [x-req-auth](#x-req-auth)
+- [x-tagGroups](#x-taggroups)
+
+For background on OpenAPI vendor extensions, refer to [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#specification-extensions).
+
+### Multi-language code examples [x-codesamples]
+
+When an OpenAPI operation includes the `x-codeSamples` extension, the API Explorer renders the code samples with a language selector tab. This lets users switch between available languages such as Console, cURL, Python, JavaScript, Ruby, PHP, and Java.
+
+The `x-codeSamples` extension is a JSON array of objects, each with a `lang` and `source` field:
+
+```json
+"x-codeSamples": [
+  { "lang": "Console", "source": "GET /_search" },
+  { "lang": "curl", "source": "curl -X GET ..." },
+  { "lang": "Python", "source": "resp = client.search()" }
+]
+```
+
+The code samples appear in a standalone "Code Examples" section on every operation page that has the extension, regardless of HTTP method. This means GET, DELETE, and other operations without a request body also display language tabs when `x-codeSamples` are present. When multiple languages are available, they appear as tabs. The selected language persists across operations and page navigations. When only one language is available, the example renders without a tab selector.
+
+Console is treated as the default language and appears first in the tab order when present.
+
+### Prerequisites [x-req-auth]
 
-### `x-displayName` for tags
+Add the operation-level `x-req-auth` extension to list authentication or privilege requirements that users must satisfy before calling the API.
+The API Explorer renders these lines in a **Prerequisites** section on the operation page.
+
+`x-req-auth` is a JSON array of strings.
+Each non-empty string becomes one item in the prerequisites list (leading and trailing whitespace is trimmed).
+
+```json
+{
+  "get": {
+    "operationId": "get-snapshot",
+    "responses": { "200": { "description": "ok" } },
+    "x-req-auth": [
+      "Cluster privilege: `cluster:admin/snapshot`"
+    ]
+  }
+}
+```
+
+
+
+When prerequisites are present, **Prerequisites** also appears in the on-page table of contents (after **Paths**).
+When the extension is missing, empty, or not a JSON array, the section is omitted.
+Malformed values are skipped and the build may log a warning.
+
+### Tag labels [x-displayname]
 
 Use the `x-displayName` extension (from [Redocly](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-display-name)) on tag objects to provide user-friendly display names in navigation and landing pages while maintaining stable URLs based on the canonical tag name.
 
@@ -163,11 +219,15 @@ Use the `x-displayName` extension (from [Redocly](https://redocly.com/docs-legac
 
 **Behavior:**
 
-- When `x-displayName` is present, it's used for navigation titles and section headings in the API Explorer
+- When `x-displayName` is present, it's used for navigation titles, tag landing page titles, and section headings on the main API overview
 - When `x-displayName` is absent, the canonical tag `name` is used as a fallback
-- Navigation URLs and internal references always use the canonical tag `name` for stability
+- Tag landing page URLs and tag URL segments are derived from the canonical tag `name`
+
+:::{note}
+If two different canonical tag names normalize to the same tag landing page URL, the build fails with an error that names both tags and the colliding segment so the spec can be fixed.
+:::
 
-### `x-tagGroups` for sidebar grouping
+### Tag groups [x-taggroups]
 
 Use the document-level `x-tagGroups` extension (from [Redocly](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-tag-groups)) to define how tags are grouped in the API Explorer sidebar. Each group has a display `name` and a list of tag `name` values that belong to it. Group order in the array is the order of top-level sections in the navigation.
 
@@ -192,5 +252,6 @@ Use the document-level `x-tagGroups` extension (from [Redocly](https://redocly.c
 **Behavior:**
 
 - When `x-tagGroups` is present and valid, the API Explorer uses it as an additional level of grouping in the sidebar.
+- In the navigation tree, a group's section title links to the **main API overview** for that product (it is not a separate page and does not point at the first tag in the group; tag landings stay under `.../tags/...` only for tags).
 - When `x-tagGroups` is absent, tags are listed directly under the API root in a single flat layer.
 - Any operation tag that is not listed under any group is still included: it appears under a fallback section named `unknown`, and the build logs a warning so you can fix the spec.