[Docs][Visualizations API] Add endpoint and field descriptions

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: {

src/platform/packages/shared/kbn-content-management-utils/src/schema.ts

@@ -31,7 +31,7 @@
 export const savedObjectSchema = <T extends ObjectType<any>>(attributesSchema: T) =>
   schema.object(
     {
-      id: schema.string(),
+      id: schema.string({ meta: { description: 'Unique identifier.' } }),
       type: schema.string(),
       version: schema.maybe(schema.string()),
       createdAt: schema.maybe(schema.string()),
@@ -77,7 +77,14 @@
 export const createOptionsSchemas = {
   id: schema.maybe(schema.string()),
   references: schema.maybe(referencesSchema),
-  overwrite: schema.maybe(schema.boolean()),
+  overwrite: schema.maybe(
+    schema.boolean({
+      meta: {
+        description:
+          'When `true`, replaces an existing saved object with the same ID. Defaults to `false`.',
+      },
+    })
+  ),
   version: schema.maybe(schema.string()),
   refresh: schema.maybe(schema.boolean()),
   initialNamespaces: schema.maybe(schema.arrayOf(schema.string())),
@@ -88,13 +95,25 @@
 
 // its recommended to create a subset of this schema for stricter validation
 export const searchOptionsSchemas = {
-  page: schema.maybe(schema.number()),
-  perPage: schema.maybe(schema.number()),
+  page: schema.maybe(schema.number({ meta: { description: 'Page number.' } })),
+  perPage: schema.maybe(schema.number({ meta: { description: 'Number of results per page.' } })),
   sortField: schema.maybe(schema.string()),
   sortOrder: schema.maybe(schema.oneOf([schema.literal('asc'), schema.literal('desc')])),
-  fields: schema.maybe(schema.arrayOf(schema.string())),
+  fields: schema.maybe(
+    schema.arrayOf(schema.string(), {
+      meta: {
+        description: 'Fields to include in each result. When omitted, all fields are returned.',
+      },
+    })
+  ),
   search: schema.maybe(schema.string()),
-  searchFields: schema.maybe(schema.oneOf([schema.string(), schema.arrayOf(schema.string())])),
+  searchFields: schema.maybe(
+    schema.oneOf([schema.string(), schema.arrayOf(schema.string())], {
+      meta: {
+        description: 'Fields to search within. Has no effect when no search query is specified.',
+      },
+    })
+  ),
   rootSearchFields: schema.maybe(schema.arrayOf(schema.string())),
 
   hasReference: schema.maybe(schema.oneOf([referenceSchema, schema.arrayOf(referenceSchema)])),

x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/create.ts

@@ -34,11 +34,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: {

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: {

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: {

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.',
       },
     }),
   },

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.',
       },
     }),
   },

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' }
 );

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.',
       },
     }),
   },

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: {

x-pack/platform/plugins/shared/lens/server/api/routes/visualizations/update.ts

@@ -37,13 +37,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: {