--- title: API Explorer description: The API Explorer renders OpenAPI specifications as interactive API documentation. When you configure it in your content set, docs-builder automatically... url: https://docs-v3-preview.elastic.dev/docs-builder/schema-support/api-explorer products: - Elastic Docs Builder --- # API Explorer The API Explorer renders OpenAPI specifications as interactive API documentation. When you configure it in your content set, `docs-builder` automatically generates pages for each API operation, request and response schemas, shared type definitions, and inline examples. This feature is still under development and the functionality described on this page might change. ## 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`. ### Basic configuration ```yaml api: elasticsearch: elasticsearch-openapi.json kibana: kibana-openapi.json ``` Each product key produces its own section of API documentation. For example, `elasticsearch` generates pages under `/api/elasticsearch/` and `kibana` generates pages under `/api/kibana/`. The `api` key is only valid in `docset.yml`. You can't use it in `toc.yml` files. ### Advanced configuration with intro and outro pages You can add custom Markdown content before and after the auto-generated API documentation using a sequence format: ```yaml api: kibana: - file: kibana-intro.md - spec: kibana-openapi.json - file: kibana-additional-notes.md ``` This configuration creates a navigation structure where: 1. **Intro pages** (before the first `spec`) appear at the top of the sidebar 2. **Generated API content** (operations, tags, types) appears in the middle 3. **Outro pages** (after the spec) appear at the bottom #### Intro and outro page features: - **Full Myst support**: Intro/outro pages support the full range of Myst Markdown features including cross-links, substitutions, and directives - **Automatic exclusion**: No need to add intro/outro files to the `exclude:` list - they're automatically excluded from normal HTML generation - **URL collision detection**: Build fails if intro/outro page names conflict with reserved API Explorer segments (`types/`, `tags/`) or operation names #### Multiple intro/outro pages You can include multiple intro and outro pages: ```yaml api: kibana: - file: introduction.md - file: getting-started.md - spec: kibana-openapi.json - file: examples.md - file: troubleshooting.md ``` #### Sample intro page Here's a sample intro page (`kibana-intro.md`): ```markdown # Kibana APIs Welcome to the Kibana API documentation. These APIs allow you to manage Kibana programmatically. ## Before you begin Make sure you have: - A running Kibana instance - Valid authentication credentials - Understanding of RESTful API principles ``` Intro and outro Markdown files must not use a slug that would collide with the reserved API Explorer segments like `types` and `tags`. ## What you can extend (and what you can't) `file:` entries in the `api:` sequence add standalone pages to the API navigation. They are the only way to inject hand-written content into an API reference section: - **Intro pages** (before the spec) and **outro pages** (after the spec) are fully rendered Markdown pages with access to all MyST directives, substitutions, and cross-links. - Intro/outro files are automatically excluded from normal HTML generation — you do not need to add them to the `exclude:` list. **What you cannot do today:** there is no way to override or augment an individual operation, tag, schema, or parameter description using a local Markdown file. Every description for generated operations, tags, and schema types comes verbatim from the OpenAPI JSON. For per-operation and per-parameter enrichment see the [CLI reference](https://docs-v3-preview.elastic.dev/docs-builder/schema-support/cli-schema), which provides a fine-grained supplemental mechanism as a reference model for what future API augmentation could look like. ### Intro/outro file naming and validation A file's URL slug is derived from its filename: lowercase, with spaces and underscores replaced by hyphens, and the `.md` extension removed. For example, `Getting-Started.md` becomes the slug `getting-started`. The following slugs are reserved and cannot be used as intro/outro file names: | Reserved slug | Reason | |---------------|---------------------------------------------------| | `types` | API Explorer uses this path for schema type pages | | `tags` | API Explorer uses this path for tag landing pages | Additionally, the slug must not match any operation moniker already generated by the spec. The build fails with a descriptive error if either collision occurs, naming the conflicting file and the reserved or operation segment. If the same slug is produced by two different intro/outro files in the same product, the build also fails with a duplicate-slug error. ### One spec per product Each product key in the `api:` block must have **exactly one** `spec:` entry. The build fails if a product sequence contains zero or more than one spec. Multiple specs per product are not currently supported. ## 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. For example, if your content set is structured like this: ``` docs/ docset.yml elasticsearch-openapi.json kibana-openapi.json index.md ... ``` Your `docset.yml` references the specs as follows: ```yaml api: elasticsearch: elasticsearch-openapi.json kibana: kibana-openapi.json ``` ## When the API Explorer runs The API Explorer generates documentation in two scenarios: - **`docs-builder build`**: API docs are generated as part of the standard build. Use `--skip-api` to skip generation for faster iteration on content. - **`docs-builder serve`**: API docs are generated on startup and regenerated automatically when spec files change. API generation is skipped when running `docs-builder serve --watch`. This is a performance optimization for `dotnet watch` workflows. Run `serve` without `--watch` to include API docs in your local preview. ## Link to API pages in navigation You can reference API pages in your `toc.yml` or `docset.yml` navigation using cross-link syntax: ```yaml toc: - file: index.md - title: Elasticsearch API Reference crosslink: elasticsearch://api/elasticsearch/ ``` ## What the API Explorer renders 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 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 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 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 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. ```json { "tags": [ { "name": "tasks", "description": "The task management APIs enable you to get information about tasks currently running.", "x-displayName": "Task management" }, { "name": "ml_anomaly", "description": "Machine learning anomaly detection APIs.", "x-displayName": "Machine Learning Anomaly Detection" } ] } ``` **Behavior:** - 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 - Tag landing page URLs and tag URL segments are derived from the canonical tag `name` 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. ### Tag groups 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. ```json { "openapi": "3.0.3", "info": { "title": "Example", "version": "1.0.0" }, "paths": {}, "x-tagGroups": [ { "name": "Search & Document APIs", "tags": ["search", "document", "eql", "esql", "sql"] }, { "name": "Cluster Management", "tags": ["indices", "cluster", "snapshot"] } ] } ``` **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.