From d70d9b2a9356d82aa7207e195371a658ea0eda53 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Mon, 20 Apr 2026 15:39:35 +0200 Subject: [PATCH] [Docs][Visualizations API] Add endpoint and field descriptions (#263151) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Part of the Lens Visualizations API documentation series. **Series:** - PR 1/4: Introduction and get-started overlay — merged (#262595) - **PR 2/4 (this PR):** Endpoint descriptions and field descriptions - PR 3/4: Request code samples and response examples (#262874) - Viz PR B: Chart type schema descriptions (#263571) ## What changed ### Route files — all 5 endpoints Added `description` strings and `since: '9.4.0'` to all five routes. ### `schema/search.ts`, `schema/create.ts`, `schema/common.ts` - `query` search param: description added inline - `id` path param on delete/get/update: improved description - `total` response field: description added inline ### `schema/delete.ts`, `schema/get.ts`, `schema/update.ts` Updated `id` description to reference where the ID comes from. ### Shared package: `@kbn/as-code-shared-schemas` Added `meta.description` to all 7 fields of `asCodeMetaSchema` (`created_at`, `created_by`, `managed`, `owner`, `updated_at`, `updated_by`, `version`). > **Note:** descriptions added to `@kbn/content-management-utils` (`savedObjectSchema.id`, `searchOptionsSchemas.*`, `createOptionsSchemas.overwrite`) were **reverted** per feedback from ThomThomson — content management schemas are not part of the public as-code API surface. Descriptions for `fields`, `search_fields`, `overwrite`, and `id` will be handled via overlay fallback. ## Open items - Two CodeQL findings on `kbn-content-management-utils/src/schema.ts` (unbounded arrays) — pre-existing, not introduced by this PR - davismcphee's architectural question answered: content-management-utils changes reverted 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 (1M context) Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> (cherry picked from commit c2bbbc461b994391921301fb2960e7a0b5df929b) --- .../shared-schemas/src/schemas/meta/schema.ts | 45 ++++++++++++++++--- .../api/routes/visualizations/create.ts | 7 ++- .../api/routes/visualizations/delete.ts | 4 +- .../server/api/routes/visualizations/get.ts | 3 +- .../routes/visualizations/schema/delete.ts | 2 +- .../api/routes/visualizations/schema/get.ts | 2 +- .../routes/visualizations/schema/search.ts | 10 +++-- .../routes/visualizations/schema/update.ts | 2 +- .../api/routes/visualizations/search.ts | 4 +- .../api/routes/visualizations/update.ts | 13 ++++-- 10 files changed, 71 insertions(+), 21 deletions(-) diff --git a/src/platform/packages/shared/as-code/shared-schemas/src/schemas/meta/schema.ts b/src/platform/packages/shared/as-code/shared-schemas/src/schemas/meta/schema.ts index c0acc406497ba..2da08e30f8e39 100644 --- a/src/platform/packages/shared/as-code/shared-schemas/src/schemas/meta/schema.ts +++ b/src/platform/packages/shared/as-code/shared-schemas/src/schemas/meta/schema.ts @@ -12,13 +12,44 @@ import { schema } from '@kbn/config-schema'; export const asCodeMetaSchema = schema.object( { - created_at: schema.maybe(schema.string()), - created_by: schema.maybe(schema.string()), - managed: schema.maybe(schema.boolean()), - owner: schema.maybe(schema.string()), - updated_at: schema.maybe(schema.string()), - updated_by: schema.maybe(schema.string()), - version: schema.maybe(schema.string()), + created_at: schema.maybe( + schema.string({ + meta: { description: 'Timestamp when the object was created (ISO 8601).' }, + }) + ), + created_by: schema.maybe( + schema.string({ + meta: { description: 'User profile ID of the user who created the object.' }, + }) + ), + managed: schema.maybe( + schema.boolean({ + meta: { + description: + 'When `true`, the object is managed by Kibana and cannot be edited by users.', + }, + }) + ), + owner: schema.maybe( + schema.string({ + meta: { description: 'Identifier of the plugin or team that owns this object.' }, + }) + ), + updated_at: schema.maybe( + schema.string({ + meta: { description: 'Timestamp when the object was last updated (ISO 8601).' }, + }) + ), + updated_by: schema.maybe( + schema.string({ + meta: { description: 'User profile ID of the user who last updated the object.' }, + }) + ), + version: schema.maybe( + schema.string({ + meta: { description: 'Internal version identifier for optimistic concurrency control.' }, + }) + ), }, { meta: { diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/create.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/create.ts index 5760d7f063812..7a70a15447688 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/create.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/create.ts @@ -33,11 +33,16 @@ export const registerLensVisualizationsCreateAPIRoute: RegisterAPIRouteFn = ( path: LENS_VIS_API_PATH, access: LENS_API_ACCESS, summary: 'Create visualization', - description: 'Create a new visualization.', + description: [ + 'Creates a Lens visualization and saves it to the library.', + '', + 'ES|QL visualizations cannot be created through this endpoint.', + ].join('\n'), options: { tags: [LENS_API_TAG], availability: { stability: 'experimental', + since: '9.4.0', }, }, security: { diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/delete.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/delete.ts index 0d726ef424576..fe993f30b5962 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/delete.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/delete.ts @@ -25,11 +25,13 @@ export const registerLensVisualizationsDeleteAPIRoute: RegisterAPIRouteFn = ( path: `${LENS_VIS_API_PATH}/{id}`, access: LENS_API_ACCESS, summary: 'Delete visualization', - description: 'Delete a visualization by id.', + description: + 'Permanently deletes a Lens visualization. If the visualization is referenced by a dashboard panel, the panel shows an error after deletion.', options: { tags: [LENS_API_TAG], availability: { stability: 'experimental', + since: '9.4.0', }, }, security: { diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/get.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/get.ts index af419606aef4c..4f8dec2beab1f 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/get.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/get.ts @@ -29,11 +29,12 @@ export const registerLensVisualizationsGetAPIRoute: RegisterAPIRouteFn = ( path: `${LENS_VIS_API_PATH}/{id}`, access: LENS_API_ACCESS, summary: 'Get visualization', - description: 'Get a visualization from id.', + description: 'Returns a single Lens visualization by its ID.', options: { tags: [LENS_API_TAG], availability: { stability: 'experimental', + since: '9.4.0', }, }, security: { diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/delete.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/delete.ts index 1efe4be16e65e..d40c9fe0fe26f 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/delete.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/delete.ts @@ -11,7 +11,7 @@ export const lensDeleteRequestParamsSchema = schema.object( { id: schema.string({ meta: { - description: 'The id of a visualization.', + description: 'The visualization identifier, as returned by the create or search endpoints.', }, }), }, diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/get.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/get.ts index bd10a8994b51c..74a297250e4ea 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/get.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/get.ts @@ -13,7 +13,7 @@ export const lensGetRequestParamsSchema = schema.object( { id: schema.string({ meta: { - description: 'The id of a visualization.', + description: 'The visualization identifier, as returned by the create or search endpoints.', }, }), }, diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/search.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/search.ts index 91b882b505024..e6cff364204a4 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/search.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/search.ts @@ -17,20 +17,20 @@ export const lensSearchRequestQuerySchema = schema.object({ query: schema.maybe( schema.string({ meta: { - description: 'The text to search for Lens visualizations', + description: 'Text to match against `search_fields`.', }, }) ), page: schema.number({ meta: { - description: 'Specifies the current page number of the paginated result.', + description: 'Page number.', }, min: 1, defaultValue: 1, }), per_page: schema.number({ meta: { - description: 'Maximum number of Lens visualizations included in a single response', + description: 'Results per page.', }, defaultValue: 20, min: 1, @@ -42,7 +42,9 @@ const lensSearchResponseMetaSchema = schema.object( { page: searchOptionsSchemas.page, per_page: searchOptionsSchemas.perPage, - total: schema.number(), // TODO use shared definition + total: schema.number({ + meta: { description: 'Total number of matching visualizations.' }, + }), }, { unknowns: 'forbid' } ); diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/update.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/update.ts index 7dcf90d2dbf8c..88b00c88c4066 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/update.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/schema/update.ts @@ -14,7 +14,7 @@ export const lensUpdateRequestParamsSchema = schema.object( { id: schema.string({ meta: { - description: 'The id of a visualization.', + description: 'The visualization identifier, as returned by the create or search endpoints.', }, }), }, diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/search.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/search.ts index d886e8b894943..7d265274a5807 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/search.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/search.ts @@ -28,11 +28,13 @@ export const registerLensVisualizationsSearchAPIRoute: RegisterAPIRouteFn = ( path: LENS_VIS_API_PATH, access: LENS_API_ACCESS, summary: 'Search visualizations', - description: 'Get list of visualizations.', + description: + 'Returns a paginated list of Lens visualizations matching the optional `query` text.', options: { tags: [LENS_API_TAG], availability: { stability: 'experimental', + since: '9.4.0', }, }, security: { diff --git a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/update.ts b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/update.ts index 5b1cae186a46f..41903a3c4f173 100644 --- a/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/update.ts +++ b/x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/update.ts @@ -34,13 +34,20 @@ export const registerLensVisualizationsUpdateAPIRoute: RegisterAPIRouteFn = ( const updateRoute = router.put({ path: `${LENS_VIS_API_PATH}/{id}`, access: LENS_API_ACCESS, - summary: 'Create or update visualization', - description: - 'Create or update a visualization with the given id. When no visualization exists for the id, one is created.', + summary: 'Update visualization', + description: [ + 'Replaces the full configuration of an existing Lens visualization. Partial updates are not supported.', + 'To make incremental changes, retrieve the visualization first, modify the fields you need, then send the complete object back.', + '', + 'If no visualization exists with the specified ID, a new one is created.', + '', + 'ES|QL visualizations cannot be updated through this endpoint.', + ].join('\n'), options: { tags: [LENS_API_TAG], availability: { stability: 'experimental', + since: '9.4.0', }, }, security: {