[Docs][Dashboards API] Add introduction and get-started overlay#262396
Merged
Conversation
Adds the tag description overlay for the Dashboards API, covering: - When to use this API vs the Visualizations API - Get started section with auth, CSRF, and spaces prerequisites - Runnable curl example using Kibana sample data - Dashboard structure model and grid explanation - Panel types reference table (content panels + observability types) - Embedding visualizations (inline vs linked from library) - ES|QL visualizations section - Makefile wired to apply the overlay in the pipeline Also adds meta.id to discriminated union entries in the controls schemas (controls_group_schema.ts, options_list_schema.ts) to unblock OAS generation for the /api/dashboards routes. This is the first in a series of focused PRs replacing #260969. Subsequent PRs will cover endpoint descriptions, request/response examples, and Bump rendering simplification. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
CI regenerates and auto-commits oas_docs/output/kibana.yaml and kibana.serverless.yaml via the Check OAS Snapshot step. No need to carry these large diffs in the PR. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
- Move 'Try it now' to ### (nested under Get started) - Expand grid and metrics JSON in the curl example - Add 'Kibana saved object ID' wording with link to saved objects docs - Add descriptive lead-in sentence for the curl example Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
CI will regenerate these via the Check OAS Snapshot step. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
The 'attributes' wrapper has been removed from the vis panel config — visualization properties are now flattened directly into 'config'. Update all inline examples and prose references accordingly. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
florent-leborgne
added
Team:Docs
release_note:skip
Contributor
|
Pinging @elastic/experience-docs (Team:Docs) |
markov00
reviewed
Apr 10, 2026
- Replace savedObjectId with ref_id in linked-from-library example - Remove operation: "value" from ES|QL metric example (no longer needed) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
- Broaden 'When to use' to cover both data view and ES|QL visualizations - Replace metric example with XY line chart (Total log entries over time) - Update vis panel type description to mention both data view and ES|QL modes - Move control panels table before observability types for better visibility - Reorder panel object fields in examples: grid, type, config Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
teresaalvarezsoler
approved these changes
Apr 10, 2026
Contributor
|
I tried accessing https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards and the |
nreese
reviewed
Apr 10, 2026
Metric (KPI) panels should use quarter width per dashboard layout best practices. Updated both inline and linked-from-library examples from w:24, h:10 to w:12, h:8. XY line and ES|QL metric examples were already correct. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
nastasha-solomon
approved these changes
Apr 13, 2026
ThomThomson
approved these changes
Apr 13, 2026
Contributor
ThomThomson
left a comment
ThomThomson
left a comment
There was a problem hiding this comment.
Changes look good! Thank you for addressing all the requested changes!
Contributor
|
Starting backport for target branches: 9.4 https://github.com/elastic/kibana/actions/runs/24354457403 |
kibanamachine
added a commit
to kibanamachine/kibana
that referenced
this pull request
Apr 13, 2026
…tic#262396) ## Summary This is the first in a series of focused PRs documenting the Dashboards API for public release. The initial investigation and content drafting was done in elastic#260969 — this series breaks that work into smaller, reviewable chunks. ### This PR (1/4) — Introduction and get-started overlay Adds \`oas_docs/overlays/dashboards.overlays.yaml\`, which sets the tag description for the \`Dashboards\` API group. The overlay covers: - **When to use this API** vs the Visualizations API - **Get started** — auth, CSRF header, and spaces prerequisites, followed by a runnable \`curl\` example (ES|QL line chart using Kibana sample data) - **Dashboard structure** — data model (\`title\`, \`panels\`, \`pinned_panels\`, \`filters\`/\`query\`/\`time_range\`), 48-column grid explanation, and controls placement (sections vs pinned) - **Panel types** — all panel types in a single table (\`vis\`, \`discover_session\`, \`image\`, \`markdown\`, filter controls), observability types (SLO, Synthetics), and a callout for types not yet supported by the REST API (write operations return \`400\`; read operations strip the panel and return a warning) - **Embedding library items** — inline (full config in \`config\`) vs linked-from-library (\`config.ref_id\`) patterns, with working examples and a link to the Visualizations API for the full vis schema - **ES|QL visualizations** — how to use \`data_source.type: "esql"\` with metric and xy chart examples Also wires the overlay into the makefile pipeline. ### Upcoming PRs in this series | PR | Content | |----|---------| | 2/4 | Improved descriptions and titles for all 5 endpoints and their request/response schemas | | 3/4 | Request/response examples for each endpoint | | 4/4 | Bump rendering simplification (strip \`additionalProperties\`, schema ID cleanup, panel type title transforms) | ## Preview https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards ## Test plan To preview locally: \`\`\`bash make -C oas_docs merge-api-docs-stateful make -C oas_docs api-docs-overlay make -C oas_docs api-docs-preview \`\`\` - [ ] \`make -C oas_docs merge-api-docs-stateful\` generates \`output/kibana.yaml\` with \`/api/dashboards\` endpoints present - [ ] \`make -C oas_docs api-docs-overlay\` applies the dashboards overlay without errors - [ ] \`make -C oas_docs api-docs-preview\` opens a Bump preview showing the Dashboards tag with the full introduction 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> (cherry picked from commit d1ec64f)
Contributor
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
3 tasks
kibanamachine
added a commit
that referenced
this pull request
Apr 13, 2026
…#262396) (#262853) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Dashboards API] Add introduction and get-started overlay (#262396)](#262396) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Florent LB","email":"florent.leborgne@elastic.co"},"sourceCommit":{"committedDate":"2026-04-13T16:25:28Z","message":"[Docs][Dashboards API] Add introduction and get-started overlay (#262396)\n\n## Summary\n\nThis is the first in a series of focused PRs documenting the Dashboards\nAPI for public release. The initial investigation and content drafting\nwas done in #260969 — this series breaks that work into smaller,\nreviewable chunks.\n\n### This PR (1/4) — Introduction and get-started overlay\n\nAdds \\`oas_docs/overlays/dashboards.overlays.yaml\\`, which sets the tag\ndescription for the \\`Dashboards\\` API group. The overlay covers:\n\n- **When to use this API** vs the Visualizations API\n- **Get started** — auth, CSRF header, and spaces prerequisites,\nfollowed by a runnable \\`curl\\` example (ES|QL line chart using Kibana\nsample data)\n- **Dashboard structure** — data model (\\`title\\`, \\`panels\\`,\n\\`pinned_panels\\`, \\`filters\\`/\\`query\\`/\\`time_range\\`), 48-column grid\nexplanation, and controls placement (sections vs pinned)\n- **Panel types** — all panel types in a single table (\\`vis\\`,\n\\`discover_session\\`, \\`image\\`, \\`markdown\\`, filter controls),\nobservability types (SLO, Synthetics), and a callout for types not yet\nsupported by the REST API (write operations return \\`400\\`; read\noperations strip the panel and return a warning)\n- **Embedding library items** — inline (full config in \\`config\\`) vs\nlinked-from-library (\\`config.ref_id\\`) patterns, with working examples\nand a link to the Visualizations API for the full vis schema\n- **ES|QL visualizations** — how to use \\`data_source.type: \"esql\"\\`\nwith metric and xy chart examples\n\nAlso wires the overlay into the makefile pipeline.\n\n### Upcoming PRs in this series\n\n| PR | Content |\n|----|---------|\n| 2/4 | Improved descriptions and titles for all 5 endpoints and their\nrequest/response schemas |\n| 3/4 | Request/response examples for each endpoint |\n| 4/4 | Bump rendering simplification (strip \\`additionalProperties\\`,\nschema ID cleanup, panel type title transforms) |\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards\n\n## Test plan\n\nTo preview locally:\n\\`\\`\\`bash\nmake -C oas_docs merge-api-docs-stateful\nmake -C oas_docs api-docs-overlay\nmake -C oas_docs api-docs-preview\n\\`\\`\\`\n\n- [ ] \\`make -C oas_docs merge-api-docs-stateful\\` generates\n\\`output/kibana.yaml\\` with \\`/api/dashboards\\` endpoints present\n- [ ] \\`make -C oas_docs api-docs-overlay\\` applies the dashboards\noverlay without errors\n- [ ] \\`make -C oas_docs api-docs-preview\\` opens a Bump preview showing\nthe Dashboards tag with the full introduction\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"d1ec64fb0ca0d93169a3bd6739c45f41ce02ce64","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","docs","APIDocs","backport:version","v9.4.0","v9.5.0"],"title":"[Docs][Dashboards API] Add introduction and get-started overlay","number":262396,"url":"https://github.com/elastic/kibana/pull/262396","mergeCommit":{"message":"[Docs][Dashboards API] Add introduction and get-started overlay (#262396)\n\n## Summary\n\nThis is the first in a series of focused PRs documenting the Dashboards\nAPI for public release. The initial investigation and content drafting\nwas done in #260969 — this series breaks that work into smaller,\nreviewable chunks.\n\n### This PR (1/4) — Introduction and get-started overlay\n\nAdds \\`oas_docs/overlays/dashboards.overlays.yaml\\`, which sets the tag\ndescription for the \\`Dashboards\\` API group. The overlay covers:\n\n- **When to use this API** vs the Visualizations API\n- **Get started** — auth, CSRF header, and spaces prerequisites,\nfollowed by a runnable \\`curl\\` example (ES|QL line chart using Kibana\nsample data)\n- **Dashboard structure** — data model (\\`title\\`, \\`panels\\`,\n\\`pinned_panels\\`, \\`filters\\`/\\`query\\`/\\`time_range\\`), 48-column grid\nexplanation, and controls placement (sections vs pinned)\n- **Panel types** — all panel types in a single table (\\`vis\\`,\n\\`discover_session\\`, \\`image\\`, \\`markdown\\`, filter controls),\nobservability types (SLO, Synthetics), and a callout for types not yet\nsupported by the REST API (write operations return \\`400\\`; read\noperations strip the panel and return a warning)\n- **Embedding library items** — inline (full config in \\`config\\`) vs\nlinked-from-library (\\`config.ref_id\\`) patterns, with working examples\nand a link to the Visualizations API for the full vis schema\n- **ES|QL visualizations** — how to use \\`data_source.type: \"esql\"\\`\nwith metric and xy chart examples\n\nAlso wires the overlay into the makefile pipeline.\n\n### Upcoming PRs in this series\n\n| PR | Content |\n|----|---------|\n| 2/4 | Improved descriptions and titles for all 5 endpoints and their\nrequest/response schemas |\n| 3/4 | Request/response examples for each endpoint |\n| 4/4 | Bump rendering simplification (strip \\`additionalProperties\\`,\nschema ID cleanup, panel type title transforms) |\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards\n\n## Test plan\n\nTo preview locally:\n\\`\\`\\`bash\nmake -C oas_docs merge-api-docs-stateful\nmake -C oas_docs api-docs-overlay\nmake -C oas_docs api-docs-preview\n\\`\\`\\`\n\n- [ ] \\`make -C oas_docs merge-api-docs-stateful\\` generates\n\\`output/kibana.yaml\\` with \\`/api/dashboards\\` endpoints present\n- [ ] \\`make -C oas_docs api-docs-overlay\\` applies the dashboards\noverlay without errors\n- [ ] \\`make -C oas_docs api-docs-preview\\` opens a Bump preview showing\nthe Dashboards tag with the full introduction\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"d1ec64fb0ca0d93169a3bd6739c45f41ce02ce64"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/262396","number":262396,"mergeCommit":{"message":"[Docs][Dashboards API] Add introduction and get-started overlay (#262396)\n\n## Summary\n\nThis is the first in a series of focused PRs documenting the Dashboards\nAPI for public release. The initial investigation and content drafting\nwas done in #260969 — this series breaks that work into smaller,\nreviewable chunks.\n\n### This PR (1/4) — Introduction and get-started overlay\n\nAdds \\`oas_docs/overlays/dashboards.overlays.yaml\\`, which sets the tag\ndescription for the \\`Dashboards\\` API group. The overlay covers:\n\n- **When to use this API** vs the Visualizations API\n- **Get started** — auth, CSRF header, and spaces prerequisites,\nfollowed by a runnable \\`curl\\` example (ES|QL line chart using Kibana\nsample data)\n- **Dashboard structure** — data model (\\`title\\`, \\`panels\\`,\n\\`pinned_panels\\`, \\`filters\\`/\\`query\\`/\\`time_range\\`), 48-column grid\nexplanation, and controls placement (sections vs pinned)\n- **Panel types** — all panel types in a single table (\\`vis\\`,\n\\`discover_session\\`, \\`image\\`, \\`markdown\\`, filter controls),\nobservability types (SLO, Synthetics), and a callout for types not yet\nsupported by the REST API (write operations return \\`400\\`; read\noperations strip the panel and return a warning)\n- **Embedding library items** — inline (full config in \\`config\\`) vs\nlinked-from-library (\\`config.ref_id\\`) patterns, with working examples\nand a link to the Visualizations API for the full vis schema\n- **ES|QL visualizations** — how to use \\`data_source.type: \"esql\"\\`\nwith metric and xy chart examples\n\nAlso wires the overlay into the makefile pipeline.\n\n### Upcoming PRs in this series\n\n| PR | Content |\n|----|---------|\n| 2/4 | Improved descriptions and titles for all 5 endpoints and their\nrequest/response schemas |\n| 3/4 | Request/response examples for each endpoint |\n| 4/4 | Bump rendering simplification (strip \\`additionalProperties\\`,\nschema ID cleanup, panel type title transforms) |\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards\n\n## Test plan\n\nTo preview locally:\n\\`\\`\\`bash\nmake -C oas_docs merge-api-docs-stateful\nmake -C oas_docs api-docs-overlay\nmake -C oas_docs api-docs-preview\n\\`\\`\\`\n\n- [ ] \\`make -C oas_docs merge-api-docs-stateful\\` generates\n\\`output/kibana.yaml\\` with \\`/api/dashboards\\` endpoints present\n- [ ] \\`make -C oas_docs api-docs-overlay\\` applies the dashboards\noverlay without errors\n- [ ] \\`make -C oas_docs api-docs-preview\\` opens a Bump preview showing\nthe Dashboards tag with the full introduction\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"d1ec64fb0ca0d93169a3bd6739c45f41ce02ce64"}}]}] BACKPORT--> Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
5 tasks
florent-leborgne
added a commit
that referenced
this pull request
Apr 14, 2026
…262595) ## Summary Adds the tag description overlay for the Visualizations API, including an intro, when to use, get started prereqs, a runnable "Try it now" example, a visualization structure overview, and a chart types table. - `oas_docs/overlays/visualizations.overlays.yaml` — new tag description overlay - `oas_docs/makefile` — wires the overlay into the stateful OAS pipeline Mirrors the scope and structure of the Dashboards API PR 1/4 (#262396). No output files committed — the overlay takes effect when the publishing pipeline runs against the full bundle. **Preview:** https://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations ## Part of series - PR 1/4 — intro + get started overlay (this PR) - PR 2/4 — improved endpoint descriptions and response schemas - PR 3/4 — request/response examples per endpoint - PR 4/4 — schema cleanup ## Test plan - [ ] `make api-docs-overlay` exits 0 - [ ] "Try it now" curl runs successfully against a local Kibana with sample logs installed - [ ] Tag description renders correctly in the preview link above --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
kibanamachine
pushed a commit
to kibanamachine/kibana
that referenced
this pull request
Apr 14, 2026
…lastic#262595) ## Summary Adds the tag description overlay for the Visualizations API, including an intro, when to use, get started prereqs, a runnable "Try it now" example, a visualization structure overview, and a chart types table. - `oas_docs/overlays/visualizations.overlays.yaml` — new tag description overlay - `oas_docs/makefile` — wires the overlay into the stateful OAS pipeline Mirrors the scope and structure of the Dashboards API PR 1/4 (elastic#262396). No output files committed — the overlay takes effect when the publishing pipeline runs against the full bundle. **Preview:** https://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations ## Part of series - PR 1/4 — intro + get started overlay (this PR) - PR 2/4 — improved endpoint descriptions and response schemas - PR 3/4 — request/response examples per endpoint - PR 4/4 — schema cleanup ## Test plan - [ ] `make api-docs-overlay` exits 0 - [ ] "Try it now" curl runs successfully against a local Kibana with sample logs installed - [ ] Tag description renders correctly in the preview link above --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> (cherry picked from commit 6eacdb4)
kibanamachine
added a commit
that referenced
this pull request
Apr 14, 2026
…rlay (#262595) (#263007) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Visualizations API] Add introduction and get-started overlay (#262595)](#262595) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Florent LB","email":"florent.leborgne@elastic.co"},"sourceCommit":{"committedDate":"2026-04-14T10:21:35Z","message":"[Docs][Visualizations API] Add introduction and get-started overlay (#262595)\n\n## Summary\n\nAdds the tag description overlay for the Visualizations API, including\nan intro, when to use, get started prereqs, a runnable \"Try it now\"\nexample, a visualization structure overview, and a chart types table.\n\n- `oas_docs/overlays/visualizations.overlays.yaml` — new tag description\noverlay\n- `oas_docs/makefile` — wires the overlay into the stateful OAS pipeline\n\nMirrors the scope and structure of the Dashboards API PR 1/4 (#262396).\nNo output files committed — the overlay takes effect when the publishing\npipeline runs against the full bundle.\n\n**Preview:**\nhttps://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations\n\n## Part of series\n- PR 1/4 — intro + get started overlay (this PR)\n- PR 2/4 — improved endpoint descriptions and response schemas\n- PR 3/4 — request/response examples per endpoint\n- PR 4/4 — schema cleanup\n\n## Test plan\n- [ ] `make api-docs-overlay` exits 0\n- [ ] \"Try it now\" curl runs successfully against a local Kibana with\nsample logs installed\n- [ ] Tag description renders correctly in the preview link above\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>","sha":"6eacdb4383e1d40f8ce99ec986d6c3ae24443529","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","docs","APIDocs","backport:version","v9.4.0","v9.5.0"],"title":"[Docs][Visualizations API] Add introduction and get-started overlay","number":262595,"url":"https://github.com/elastic/kibana/pull/262595","mergeCommit":{"message":"[Docs][Visualizations API] Add introduction and get-started overlay (#262595)\n\n## Summary\n\nAdds the tag description overlay for the Visualizations API, including\nan intro, when to use, get started prereqs, a runnable \"Try it now\"\nexample, a visualization structure overview, and a chart types table.\n\n- `oas_docs/overlays/visualizations.overlays.yaml` — new tag description\noverlay\n- `oas_docs/makefile` — wires the overlay into the stateful OAS pipeline\n\nMirrors the scope and structure of the Dashboards API PR 1/4 (#262396).\nNo output files committed — the overlay takes effect when the publishing\npipeline runs against the full bundle.\n\n**Preview:**\nhttps://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations\n\n## Part of series\n- PR 1/4 — intro + get started overlay (this PR)\n- PR 2/4 — improved endpoint descriptions and response schemas\n- PR 3/4 — request/response examples per endpoint\n- PR 4/4 — schema cleanup\n\n## Test plan\n- [ ] `make api-docs-overlay` exits 0\n- [ ] \"Try it now\" curl runs successfully against a local Kibana with\nsample logs installed\n- [ ] Tag description renders correctly in the preview link above\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>","sha":"6eacdb4383e1d40f8ce99ec986d6c3ae24443529"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/262595","number":262595,"mergeCommit":{"message":"[Docs][Visualizations API] Add introduction and get-started overlay (#262595)\n\n## Summary\n\nAdds the tag description overlay for the Visualizations API, including\nan intro, when to use, get started prereqs, a runnable \"Try it now\"\nexample, a visualization structure overview, and a chart types table.\n\n- `oas_docs/overlays/visualizations.overlays.yaml` — new tag description\noverlay\n- `oas_docs/makefile` — wires the overlay into the stateful OAS pipeline\n\nMirrors the scope and structure of the Dashboards API PR 1/4 (#262396).\nNo output files committed — the overlay takes effect when the publishing\npipeline runs against the full bundle.\n\n**Preview:**\nhttps://bump.sh/elastic/hub/elastic-apis/doc/visualizations-api-cleanup-intro-get-started/group/endpoint-visualizations\n\n## Part of series\n- PR 1/4 — intro + get started overlay (this PR)\n- PR 2/4 — improved endpoint descriptions and response schemas\n- PR 3/4 — request/response examples per endpoint\n- PR 4/4 — schema cleanup\n\n## Test plan\n- [ ] `make api-docs-overlay` exits 0\n- [ ] \"Try it now\" curl runs successfully against a local Kibana with\nsample logs installed\n- [ ] Tag description renders correctly in the preview link above\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>","sha":"6eacdb4383e1d40f8ce99ec986d6c3ae24443529"}}]}] BACKPORT--> Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
This was referenced Apr 14, 2026
florent-leborgne
added a commit
that referenced
this pull request
Apr 16, 2026
…dpoints (#262865) ## Summary - Adds cURL and Console code samples (`x-codeSamples`) to all 5 Dashboards API endpoints (POST, GET `/{id}`, PUT `/{id}`, DELETE `/{id}`, GET `_find`) - POST includes two examples: simple dashboard (markdown + 2 metrics + ES|QL line chart) and a structured dashboard with sections and controls - Adds inlined response examples for POST (201), GET (200), PUT (200), and GET `_find` (200) All examples tested against a live Kibana 9.4.0 instance using the Kibana sample logs dataset (`kibana_sample_data_logs`). Follows the grid best practices documented in the tag description (PR #262396). Part of the Dashboards API documentation series: #262396 (merged) → descriptions (#263166, #263281, #263282, #263283) → this PR. ## Preview https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards ## Test plan - [ ] Generate Bump preview and verify code samples appear in upper right dropdown for each endpoint - [ ] Verify response examples appear in the Responses section - [ ] Confirm all JSON in code samples is fully expanded (no inline objects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
kibanamachine
pushed a commit
to kibanamachine/kibana
that referenced
this pull request
Apr 16, 2026
…dpoints (elastic#262865) ## Summary - Adds cURL and Console code samples (`x-codeSamples`) to all 5 Dashboards API endpoints (POST, GET `/{id}`, PUT `/{id}`, DELETE `/{id}`, GET `_find`) - POST includes two examples: simple dashboard (markdown + 2 metrics + ES|QL line chart) and a structured dashboard with sections and controls - Adds inlined response examples for POST (201), GET (200), PUT (200), and GET `_find` (200) All examples tested against a live Kibana 9.4.0 instance using the Kibana sample logs dataset (`kibana_sample_data_logs`). Follows the grid best practices documented in the tag description (PR elastic#262396). Part of the Dashboards API documentation series: elastic#262396 (merged) → descriptions (elastic#263166, elastic#263281, elastic#263282, elastic#263283) → this PR. ## Preview https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards ## Test plan - [ ] Generate Bump preview and verify code samples appear in upper right dropdown for each endpoint - [ ] Verify response examples appear in the Responses section - [ ] Confirm all JSON in code samples is fully expanded (no inline objects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> (cherry picked from commit f6059b0)
kibanamachine
added a commit
that referenced
this pull request
Apr 16, 2026
…l 5 endpoints (#262865) (#263899) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Dashboards API] Add request and response examples for all 5 endpoints (#262865)](#262865) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Florent LB","email":"florent.leborgne@elastic.co"},"sourceCommit":{"committedDate":"2026-04-16T20:16:43Z","message":"[Docs][Dashboards API] Add request and response examples for all 5 endpoints (#262865)\n\n## Summary\n\n- Adds cURL and Console code samples (`x-codeSamples`) to all 5\nDashboards API endpoints (POST, GET `/{id}`, PUT `/{id}`, DELETE\n`/{id}`, GET `_find`)\n- POST includes two examples: simple dashboard (markdown + 2 metrics +\nES|QL line chart) and a structured dashboard with sections and controls\n- Adds inlined response examples for POST (201), GET (200), PUT (200),\nand GET `_find` (200)\n\nAll examples tested against a live Kibana 9.4.0 instance using the\nKibana sample logs dataset (`kibana_sample_data_logs`). Follows the grid\nbest practices documented in the tag description (PR #262396).\n\nPart of the Dashboards API documentation series: #262396 (merged) →\ndescriptions (#263166, #263281, #263282, #263283) → this PR.\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards\n\n## Test plan\n\n- [ ] Generate Bump preview and verify code samples appear in upper\nright dropdown for each endpoint\n- [ ] Verify response examples appear in the Responses section\n- [ ] Confirm all JSON in code samples is fully expanded (no inline\nobjects)\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>","sha":"f6059b02aca72b0978a1da87a5c74ccb60e26325","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","docs","APIDocs","backport:version","v9.4.0","v9.5.0"],"title":"[Docs][Dashboards API] Add request and response examples for all 5 endpoints","number":262865,"url":"https://github.com/elastic/kibana/pull/262865","mergeCommit":{"message":"[Docs][Dashboards API] Add request and response examples for all 5 endpoints (#262865)\n\n## Summary\n\n- Adds cURL and Console code samples (`x-codeSamples`) to all 5\nDashboards API endpoints (POST, GET `/{id}`, PUT `/{id}`, DELETE\n`/{id}`, GET `_find`)\n- POST includes two examples: simple dashboard (markdown + 2 metrics +\nES|QL line chart) and a structured dashboard with sections and controls\n- Adds inlined response examples for POST (201), GET (200), PUT (200),\nand GET `_find` (200)\n\nAll examples tested against a live Kibana 9.4.0 instance using the\nKibana sample logs dataset (`kibana_sample_data_logs`). Follows the grid\nbest practices documented in the tag description (PR #262396).\n\nPart of the Dashboards API documentation series: #262396 (merged) →\ndescriptions (#263166, #263281, #263282, #263283) → this PR.\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards\n\n## Test plan\n\n- [ ] Generate Bump preview and verify code samples appear in upper\nright dropdown for each endpoint\n- [ ] Verify response examples appear in the Responses section\n- [ ] Confirm all JSON in code samples is fully expanded (no inline\nobjects)\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>","sha":"f6059b02aca72b0978a1da87a5c74ccb60e26325"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/262865","number":262865,"mergeCommit":{"message":"[Docs][Dashboards API] Add request and response examples for all 5 endpoints (#262865)\n\n## Summary\n\n- Adds cURL and Console code samples (`x-codeSamples`) to all 5\nDashboards API endpoints (POST, GET `/{id}`, PUT `/{id}`, DELETE\n`/{id}`, GET `_find`)\n- POST includes two examples: simple dashboard (markdown + 2 metrics +\nES|QL line chart) and a structured dashboard with sections and controls\n- Adds inlined response examples for POST (201), GET (200), PUT (200),\nand GET `_find` (200)\n\nAll examples tested against a live Kibana 9.4.0 instance using the\nKibana sample logs dataset (`kibana_sample_data_logs`). Follows the grid\nbest practices documented in the tag description (PR #262396).\n\nPart of the Dashboards API documentation series: #262396 (merged) →\ndescriptions (#263166, #263281, #263282, #263283) → this PR.\n\n## Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards\n\n## Test plan\n\n- [ ] Generate Bump preview and verify code samples appear in upper\nright dropdown for each endpoint\n- [ ] Verify response examples appear in the Responses section\n- [ ] Confirm all JSON in code samples is fully expanded (no inline\nobjects)\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>","sha":"f6059b02aca72b0978a1da87a5c74ccb60e26325"}}]}] BACKPORT--> Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
florent-leborgne
added a commit
that referenced
this pull request
Apr 20, 2026
…e) (#263166) ## Summary Improves the OAS documentation for the Dashboards API by adding meaningful descriptions to endpoints, request body fields, and response fields directly in the TypeScript source. Part of the Dashboards API documentation series: - PR 1/4 ([#262396](#262396)) — Tag description + get-started overlay — **merged** - **PR 2a (this PR)** — Endpoint and field descriptions in source - PR 3/4 ([#262865](#262865)) — x-codeSamples + response examples — in review ## Changes ### Endpoint-level (`register_*.ts`) - Added `description` to all 5 endpoints - PUT `summary`: changed to `"Upsert a dashboard"` (reflects upsert semantics per reviewer feedback) - Improved path param `id` descriptions on GET and DELETE ### Search schema (`search/schemas.ts`) - `page`, `per_page`: surfaces defaults - `query`: links to `simple_query_string` docs, notes AND-operator default - Response fields: `total`, `page`, `dashboards[]` array, `dashboards[].id`, `dashboards[].data.*` - CodeQL fix: added `maxSize: 100` to response `tags` array ### Dashboard state schema (`dashboard_state_schemas.ts`) - Top-level body fields: `panels`, `filters`, `tags`, `description`, `title`, `project_routing` - Panel grid (`x`, `y`, `w`, `h`): defaults and constraints surfaced - Section schema: fixed typo (`Collapsable` → `Collapsible`), `collapsed` rewritten to explain behaviour - Options schema: all 7 booleans in `When \`true\`, … Defaults to \`X\`.` pattern - Access control schema: object description, title, and `access_mode` valid values ### Response schemas - `response.id`: added description to all CRU response schemas - `response.warnings`: added description; `droppedPanelWarningSchema` fields all described - `response.dashboards` (search): added description to outer array ## What is NOT in this PR (planned follow-ups) Five body fields are pure `$ref` properties — Bump does not surface the referenced schema description at the field level. Overlay sibling-description fallbacks are planned: - `options`, `access_control`, `query`, `time_range`, `refresh_interval` (request body) - `data.time_range`, `data.access_control` (search response) ## Test plan - [x] ESLint passes on all modified files - [x] OAS snapshot captured from combined branch and previewed in Bump 🤖 Generated with [Claude Code](https://claude.ai/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
kibanamachine
added a commit
to kibanamachine/kibana
that referenced
this pull request
Apr 20, 2026
…e) (elastic#263166) ## Summary Improves the OAS documentation for the Dashboards API by adding meaningful descriptions to endpoints, request body fields, and response fields directly in the TypeScript source. Part of the Dashboards API documentation series: - PR 1/4 ([elastic#262396](elastic#262396)) — Tag description + get-started overlay — **merged** - **PR 2a (this PR)** — Endpoint and field descriptions in source - PR 3/4 ([elastic#262865](elastic#262865)) — x-codeSamples + response examples — in review ## Changes ### Endpoint-level (`register_*.ts`) - Added `description` to all 5 endpoints - PUT `summary`: changed to `"Upsert a dashboard"` (reflects upsert semantics per reviewer feedback) - Improved path param `id` descriptions on GET and DELETE ### Search schema (`search/schemas.ts`) - `page`, `per_page`: surfaces defaults - `query`: links to `simple_query_string` docs, notes AND-operator default - Response fields: `total`, `page`, `dashboards[]` array, `dashboards[].id`, `dashboards[].data.*` - CodeQL fix: added `maxSize: 100` to response `tags` array ### Dashboard state schema (`dashboard_state_schemas.ts`) - Top-level body fields: `panels`, `filters`, `tags`, `description`, `title`, `project_routing` - Panel grid (`x`, `y`, `w`, `h`): defaults and constraints surfaced - Section schema: fixed typo (`Collapsable` → `Collapsible`), `collapsed` rewritten to explain behaviour - Options schema: all 7 booleans in `When \`true\`, … Defaults to \`X\`.` pattern - Access control schema: object description, title, and `access_mode` valid values ### Response schemas - `response.id`: added description to all CRU response schemas - `response.warnings`: added description; `droppedPanelWarningSchema` fields all described - `response.dashboards` (search): added description to outer array ## What is NOT in this PR (planned follow-ups) Five body fields are pure `$ref` properties — Bump does not surface the referenced schema description at the field level. Overlay sibling-description fallbacks are planned: - `options`, `access_control`, `query`, `time_range`, `refresh_interval` (request body) - `data.time_range`, `data.access_control` (search response) ## Test plan - [x] ESLint passes on all modified files - [x] OAS snapshot captured from combined branch and previewed in Bump 🤖 Generated with [Claude Code](https://claude.ai/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> (cherry picked from commit 62fd2cd)
kibanamachine
added a commit
that referenced
this pull request
Apr 20, 2026
…(source) (#263166) (#264364) # Backport This will backport the following commits from `main` to `9.4`: - [[Docs][Dashboards API] Improve endpoint and field descriptions (source) (#263166)](#263166) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Florent LB","email":"florent.leborgne@elastic.co"},"sourceCommit":{"committedDate":"2026-04-20T10:03:38Z","message":"[Docs][Dashboards API] Improve endpoint and field descriptions (source) (#263166)\n\n## Summary\n\nImproves the OAS documentation for the Dashboards API by adding\nmeaningful descriptions to endpoints, request body fields, and response\nfields directly in the TypeScript source.\n\nPart of the Dashboards API documentation series:\n- PR 1/4 ([#262396](#262396)) —\nTag description + get-started overlay — **merged**\n- **PR 2a (this PR)** — Endpoint and field descriptions in source\n- PR 3/4 ([#262865](#262865)) —\nx-codeSamples + response examples — in review\n\n## Changes\n\n### Endpoint-level (`register_*.ts`)\n- Added `description` to all 5 endpoints\n- PUT `summary`: changed to `\"Upsert a dashboard\"` (reflects upsert\nsemantics per reviewer feedback)\n- Improved path param `id` descriptions on GET and DELETE\n\n### Search schema (`search/schemas.ts`)\n- `page`, `per_page`: surfaces defaults\n- `query`: links to `simple_query_string` docs, notes AND-operator\ndefault\n- Response fields: `total`, `page`, `dashboards[]` array,\n`dashboards[].id`, `dashboards[].data.*`\n- CodeQL fix: added `maxSize: 100` to response `tags` array\n\n### Dashboard state schema (`dashboard_state_schemas.ts`)\n- Top-level body fields: `panels`, `filters`, `tags`, `description`,\n`title`, `project_routing`\n- Panel grid (`x`, `y`, `w`, `h`): defaults and constraints surfaced\n- Section schema: fixed typo (`Collapsable` → `Collapsible`),\n`collapsed` rewritten to explain behaviour\n- Options schema: all 7 booleans in `When \\`true\\`, … Defaults to\n\\`X\\`.` pattern\n- Access control schema: object description, title, and `access_mode`\nvalid values\n\n### Response schemas\n- `response.id`: added description to all CRU response schemas\n- `response.warnings`: added description; `droppedPanelWarningSchema`\nfields all described\n- `response.dashboards` (search): added description to outer array\n\n## What is NOT in this PR (planned follow-ups)\n\nFive body fields are pure `$ref` properties — Bump does not surface the\nreferenced schema description at the field level. Overlay\nsibling-description fallbacks are planned:\n- `options`, `access_control`, `query`, `time_range`, `refresh_interval`\n(request body)\n- `data.time_range`, `data.access_control` (search response)\n\n## Test plan\n- [x] ESLint passes on all modified files\n- [x] OAS snapshot captured from combined branch and previewed in Bump\n\n🤖 Generated with [Claude Code](https://claude.ai/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"62fd2cd60ea38b5fab6f2ad1acd7046b19b63552","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","docs","APIDocs","backport:version","v9.4.0","v9.5.0"],"title":"[Docs][Dashboards API] Improve endpoint and field descriptions (source)","number":263166,"url":"https://github.com/elastic/kibana/pull/263166","mergeCommit":{"message":"[Docs][Dashboards API] Improve endpoint and field descriptions (source) (#263166)\n\n## Summary\n\nImproves the OAS documentation for the Dashboards API by adding\nmeaningful descriptions to endpoints, request body fields, and response\nfields directly in the TypeScript source.\n\nPart of the Dashboards API documentation series:\n- PR 1/4 ([#262396](#262396)) —\nTag description + get-started overlay — **merged**\n- **PR 2a (this PR)** — Endpoint and field descriptions in source\n- PR 3/4 ([#262865](#262865)) —\nx-codeSamples + response examples — in review\n\n## Changes\n\n### Endpoint-level (`register_*.ts`)\n- Added `description` to all 5 endpoints\n- PUT `summary`: changed to `\"Upsert a dashboard\"` (reflects upsert\nsemantics per reviewer feedback)\n- Improved path param `id` descriptions on GET and DELETE\n\n### Search schema (`search/schemas.ts`)\n- `page`, `per_page`: surfaces defaults\n- `query`: links to `simple_query_string` docs, notes AND-operator\ndefault\n- Response fields: `total`, `page`, `dashboards[]` array,\n`dashboards[].id`, `dashboards[].data.*`\n- CodeQL fix: added `maxSize: 100` to response `tags` array\n\n### Dashboard state schema (`dashboard_state_schemas.ts`)\n- Top-level body fields: `panels`, `filters`, `tags`, `description`,\n`title`, `project_routing`\n- Panel grid (`x`, `y`, `w`, `h`): defaults and constraints surfaced\n- Section schema: fixed typo (`Collapsable` → `Collapsible`),\n`collapsed` rewritten to explain behaviour\n- Options schema: all 7 booleans in `When \\`true\\`, … Defaults to\n\\`X\\`.` pattern\n- Access control schema: object description, title, and `access_mode`\nvalid values\n\n### Response schemas\n- `response.id`: added description to all CRU response schemas\n- `response.warnings`: added description; `droppedPanelWarningSchema`\nfields all described\n- `response.dashboards` (search): added description to outer array\n\n## What is NOT in this PR (planned follow-ups)\n\nFive body fields are pure `$ref` properties — Bump does not surface the\nreferenced schema description at the field level. Overlay\nsibling-description fallbacks are planned:\n- `options`, `access_control`, `query`, `time_range`, `refresh_interval`\n(request body)\n- `data.time_range`, `data.access_control` (search response)\n\n## Test plan\n- [x] ESLint passes on all modified files\n- [x] OAS snapshot captured from combined branch and previewed in Bump\n\n🤖 Generated with [Claude Code](https://claude.ai/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"62fd2cd60ea38b5fab6f2ad1acd7046b19b63552"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/263166","number":263166,"mergeCommit":{"message":"[Docs][Dashboards API] Improve endpoint and field descriptions (source) (#263166)\n\n## Summary\n\nImproves the OAS documentation for the Dashboards API by adding\nmeaningful descriptions to endpoints, request body fields, and response\nfields directly in the TypeScript source.\n\nPart of the Dashboards API documentation series:\n- PR 1/4 ([#262396](#262396)) —\nTag description + get-started overlay — **merged**\n- **PR 2a (this PR)** — Endpoint and field descriptions in source\n- PR 3/4 ([#262865](#262865)) —\nx-codeSamples + response examples — in review\n\n## Changes\n\n### Endpoint-level (`register_*.ts`)\n- Added `description` to all 5 endpoints\n- PUT `summary`: changed to `\"Upsert a dashboard\"` (reflects upsert\nsemantics per reviewer feedback)\n- Improved path param `id` descriptions on GET and DELETE\n\n### Search schema (`search/schemas.ts`)\n- `page`, `per_page`: surfaces defaults\n- `query`: links to `simple_query_string` docs, notes AND-operator\ndefault\n- Response fields: `total`, `page`, `dashboards[]` array,\n`dashboards[].id`, `dashboards[].data.*`\n- CodeQL fix: added `maxSize: 100` to response `tags` array\n\n### Dashboard state schema (`dashboard_state_schemas.ts`)\n- Top-level body fields: `panels`, `filters`, `tags`, `description`,\n`title`, `project_routing`\n- Panel grid (`x`, `y`, `w`, `h`): defaults and constraints surfaced\n- Section schema: fixed typo (`Collapsable` → `Collapsible`),\n`collapsed` rewritten to explain behaviour\n- Options schema: all 7 booleans in `When \\`true\\`, … Defaults to\n\\`X\\`.` pattern\n- Access control schema: object description, title, and `access_mode`\nvalid values\n\n### Response schemas\n- `response.id`: added description to all CRU response schemas\n- `response.warnings`: added description; `droppedPanelWarningSchema`\nfields all described\n- `response.dashboards` (search): added description to outer array\n\n## What is NOT in this PR (planned follow-ups)\n\nFive body fields are pure `$ref` properties — Bump does not surface the\nreferenced schema description at the field level. Overlay\nsibling-description fallbacks are planned:\n- `options`, `access_control`, `query`, `time_range`, `refresh_interval`\n(request body)\n- `data.time_range`, `data.access_control` (search response)\n\n## Test plan\n- [x] ESLint passes on all modified files\n- [x] OAS snapshot captured from combined branch and previewed in Bump\n\n🤖 Generated with [Claude Code](https://claude.ai/claude-code)\n\n---------\n\nCo-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"62fd2cd60ea38b5fab6f2ad1acd7046b19b63552"}}]}] BACKPORT--> Co-authored-by: Florent LB <florent.leborgne@elastic.co> Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
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
8 participants
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
This is the first in a series of focused PRs documenting the Dashboards API for public release. The initial investigation and content drafting was done in #260969 — this series breaks that work into smaller, reviewable chunks.
This PR (1/4) — Introduction and get-started overlay
Adds `oas_docs/overlays/dashboards.overlays.yaml`, which sets the tag description for the `Dashboards` API group. The overlay covers:
Also wires the overlay into the makefile pipeline.
Upcoming PRs in this series
Preview
https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/operation/operation-get-dashboards
Test plan
To preview locally:
```bash
make -C oas_docs merge-api-docs-stateful
make -C oas_docs api-docs-overlay
make -C oas_docs api-docs-preview
```
🤖 Generated with Claude Code