[Docs][Dashboards API] Add request and response examples for all 5 endpoints#262865
Merged
Conversation
…dpoints Adds cURL and Console code samples (x-codeSamples) and response examples for all Dashboards API endpoints: POST, GET, PUT, DELETE, and GET _find. Also fixes description text for ES|QL metric charts that incorrectly referenced the removed `operation: "value"` field. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
florent-leborgne
requested review from
ThomThomson,
markov00 and
teresaalvarezsoler
Corrects field order in all response examples to match actual API output: - `data` fields: options → panels → pinned_panels → title - Panel fields: grid → config → id → type - Search response: time_range before title Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…se description Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Expand response examples to include all server-returned fields: sampling, ignore_global_filters, empty_as_null, axis_id, styling, axis, and legend defaults. Fixes GET response field ordering (options → title → panels → pinned_panels) which differs from POST. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Member
Author
|
Note for reviewers: The POST (create) and GET response examples have different field ordering within |
3 tasks
…points
Adds lang: JSON response examples to x-codeSamples for POST, GET _find,
GET /{id}, and PUT /{id} so they reliably appear in the Bump code panel.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
… all endpoints" This reverts commit d4d5d7e.
… it in wrong location) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
… rendering Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Contributor
teresaalvarezsoler
left a comment
teresaalvarezsoler
left a comment
There was a problem hiding this comment.
Thanks @florent-leborgne. The examples look good, I just left a few comments. Maybe including markdown in one of the examples would be nice too. I would leave it to you to decide.
- Remove title from all metric panel configs (metrics use their own label) - Change metric panel height to h:5 across all examples - Fix Unique visitors panel to w:12, h:5 - Add missing titles to xy panels in sections+controls example - Add PUT description note: all panels must be included or they are removed Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Adds a markdown panel as the first panel in the simple POST example, demonstrating the markdown panel type and self-documenting the dashboard. Layout: markdown (y:0, w:24, h:10) → 2 metrics (y:10) → ES|QL xy (y:15). Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…h formatted markdown Switches from stacked to side-by-side layout: markdown (left, w:24, h:15) alongside metrics and line chart (right half). Adds spacers for vertical spacing in the markdown panel. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
… callout Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…supported in op descriptions) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
…cription Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
florent-leborgne
added
Team:Docs
release_note:skip
florent-leborgne
added
APIDocs
backport:version
Contributor
|
Pinging @elastic/experience-docs (Team:Docs) |
2 tasks
Contributor
💛 Build succeeded, but was flaky
Failed CI StepsTest Failures
Metrics [docs]
|
This was referenced Apr 16, 2026
ThomThomson
approved these changes
Apr 16, 2026
Contributor
ThomThomson
left a comment
ThomThomson
left a comment
There was a problem hiding this comment.
Read through the examples on bump and looked through the code. Looks good to me!
| - type: line | ||
| data_source: | ||
| type: esql | ||
| query: "FROM kibana_sample_data_logs | STATS count = COUNT() BY @timestamp = BUCKET(@timestamp, 75, ?_tstart, ?_tend)" |
Contributor
There was a problem hiding this comment.
Nice variety of ESQL + Data View based
Contributor
|
Starting backport for target branches: 9.4 https://github.com/elastic/kibana/actions/runs/24531855017 |
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)
Contributor
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
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
7 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
x-codeSamples) to all 5 Dashboards API endpoints (POST, GET/{id}, PUT/{id}, DELETE/{id}, GET_find)_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
🤖 Generated with Claude Code