[Dashboards][OAS] Generate API docs for Dashboards API (#199215)

.buildkite/scripts/steps/checks/capture_oas_snapshot.sh

@@ -8,7 +8,7 @@ source .buildkite/scripts/common/util.sh
 .buildkite/scripts/copy_es_snapshot_cache.sh
 
 echo --- Capture OAS snapshot
-cmd="node scripts/capture_oas_snapshot --include-path /api/status --include-path /api/alerting/rule/ --include-path /api/alerting/rules --include-path /api/actions --include-path /api/security/role --include-path /api/spaces --include-path /api/fleet"
+cmd="node scripts/capture_oas_snapshot --include-path /api/status --include-path /api/alerting/rule/ --include-path /api/alerting/rules --include-path /api/actions --include-path /api/security/role --include-path /api/spaces --include-path /api/fleet --include-path /api/dashboards"
 if is_pr && ! is_auto_commit_disabled; then
   cmd="$cmd --update"
 fi

src/plugins/dashboard/server/api/register_routes.ts

@@ -53,6 +53,9 @@ export function registerAPIRoutes({
     description: TECHNICAL_PREVIEW_WARNING,
     options: {
       tags: ['oas-tag:Dashboards'],
+      availability: {
+        stability: 'experimental',
+      },
     },
   });
 
@@ -62,7 +65,11 @@ export function registerAPIRoutes({
       validate: {
         request: {
           params: schema.object({
-            id: schema.maybe(schema.string()),
+            id: schema.maybe(
+              schema.string({
+                meta: { description: 'A unique identifier for the dashboard.' },
+              })
+            ),
           }),
           body: schema.object({
             attributes: dashboardAttributesSchema,
@@ -115,10 +122,13 @@ export function registerAPIRoutes({
   const updateRoute = versionedRouter.put({
     path: `${PUBLIC_API_PATH}/{id}`,
     access: 'public',
-    summary: `Update an existing dashboard.`,
+    summary: `Update an existing dashboard`,
     description: TECHNICAL_PREVIEW_WARNING,
     options: {
       tags: ['oas-tag:Dashboards'],
+      availability: {
+        stability: 'experimental',
+      },
     },
   });
 
@@ -128,7 +138,9 @@ export function registerAPIRoutes({
       validate: {
         request: {
           params: schema.object({
-            id: schema.string(),
+            id: schema.string({
+              meta: { description: 'A unique identifier for the dashboard.' },
+            }),
           }),
           body: schema.object({
             attributes: dashboardAttributesSchema,
@@ -172,10 +184,13 @@ export function registerAPIRoutes({
   const listRoute = versionedRouter.get({
     path: `${PUBLIC_API_PATH}`,
     access: 'public',
-    summary: `Get a list of dashboards.`,
+    summary: `Get a list of dashboards`,
     description: TECHNICAL_PREVIEW_WARNING,
     options: {
       tags: ['oas-tag:Dashboards'],
+      availability: {
+        stability: 'experimental',
+      },
     },
   });
 
@@ -185,8 +200,22 @@ export function registerAPIRoutes({
       validate: {
         request: {
           query: schema.object({
-            page: schema.number({ defaultValue: 1 }),
-            perPage: schema.maybe(schema.number()),
+            page: schema.number({
+              meta: { description: 'The page number to return. Default is "1".' },
+              min: 1,
+              defaultValue: 1,
+            }),
+            perPage: schema.maybe(
+              schema.number({
+                meta: {
+                  description:
+                    'The number of dashboards to display on each page (max 1000). Default is "20".',
+                },
+                defaultValue: 20,
+                min: 1,
+                max: 1000,
+              })
+            ),
           }),
         },
         response: {
@@ -229,10 +258,13 @@ export function registerAPIRoutes({
   const getRoute = versionedRouter.get({
     path: `${PUBLIC_API_PATH}/{id}`,
     access: 'public',
-    summary: `Get a dashboard.`,
+    summary: `Get a dashboard`,
     description: TECHNICAL_PREVIEW_WARNING,
     options: {
       tags: ['oas-tag:Dashboards'],
+      availability: {
+        stability: 'experimental',
+      },
     },
   });
 
@@ -242,7 +274,11 @@ export function registerAPIRoutes({
       validate: {
         request: {
           params: schema.object({
-            id: schema.string(),
+            id: schema.string({
+              meta: {
+                description: 'A unique identifier for the dashboard.',
+              },
+            }),
           }),
         },
         response: {
@@ -283,10 +319,13 @@ export function registerAPIRoutes({
   const deleteRoute = versionedRouter.delete({
     path: `${PUBLIC_API_PATH}/{id}`,
     access: 'public',
-    summary: `Delete a dashboard.`,
+    summary: `Delete a dashboard`,
     description: TECHNICAL_PREVIEW_WARNING,
     options: {
       tags: ['oas-tag:Dashboards'],
+      availability: {
+        stability: 'experimental',
+      },
     },
   });
 
@@ -296,7 +335,11 @@ export function registerAPIRoutes({
       validate: {
         request: {
           params: schema.object({
-            id: schema.string(),
+            id: schema.string({
+              meta: {
+                description: 'A unique identifier for the dashboard.',
+              },
+            }),
           }),
         },
       },

src/plugins/dashboard/server/content_management/v3/cm_services.ts

@@ -7,7 +7,6 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-import { v4 as uuidv4 } from 'uuid';
 import { schema, Type } from '@kbn/config-schema';
 import { createOptionsSchemas, updateOptionsSchema } from '@kbn/content-management-utils';
 import type { ContentManagementServicesDefinition as ServicesDefinition } from '@kbn/object-versioning';
@@ -50,10 +49,11 @@ export const controlGroupInputSchema = schema.object({
       {
         type: schema.string({ meta: { description: 'The type of the control panel.' } }),
         controlConfig: schema.maybe(schema.recordOf(schema.string(), schema.any())),
-        id: schema.string({
-          defaultValue: uuidv4(),
-          meta: { description: 'The unique ID of the control.' },
-        }),
+        id: schema.maybe(
+          schema.string({
+            meta: { description: 'The unique ID of the control.' },
+          })
+        ),
         order: schema.number({
           meta: {
             description: 'The order of the control panel in the control group.',
@@ -243,10 +243,11 @@ export const gridDataSchema = schema.object({
     min: 1,
     meta: { description: 'The height of the panel in grid units' },
   }),
-  i: schema.string({
-    meta: { description: 'The unique identifier of the panel' },
-    defaultValue: uuidv4(),
-  }),
+  i: schema.maybe(
+    schema.string({
+      meta: { description: 'The unique identifier of the panel' },
+    })
+  ),
 });
 
 export const panelSchema = schema.object({
@@ -284,10 +285,11 @@ export const panelSchema = schema.object({
   type: schema.string({ meta: { description: 'The embeddable type' } }),
   panelRefName: schema.maybe(schema.string()),
   gridData: gridDataSchema,
-  panelIndex: schema.string({
-    meta: { description: 'The unique ID of the panel.' },
-    defaultValue: schema.siblingRef('gridData.i'),
-  }),
+  panelIndex: schema.maybe(
+    schema.string({
+      meta: { description: 'The unique ID of the panel.' },
+    })
+  ),
   title: schema.maybe(schema.string({ meta: { description: 'The title of the panel' } })),
   version: schema.maybe(
     schema.string({
@@ -409,6 +411,19 @@ export const referenceSchema = schema.object(
   { unknowns: 'forbid' }
 );
 
+const dashboardAttributesSchemaResponse = dashboardAttributesSchema.extends({
+  panels: schema.arrayOf(
+    panelSchema.extends({
+      // Responses always include the panel index and gridData.i
+      panelIndex: schema.string(),
+      gridData: gridDataSchema.extends({
+        i: schema.string(),
+      }),
+    }),
+    { defaultValue: [] }
+  ),
+});
+
 export const dashboardItemSchema = schema.object(
   {
     id: schema.string(),
@@ -420,7 +435,7 @@ export const dashboardItemSchema = schema.object(
     updatedBy: schema.maybe(schema.string()),
     managed: schema.maybe(schema.boolean()),
     error: schema.maybe(apiError),
-    attributes: dashboardAttributesSchema,
+    attributes: dashboardAttributesSchemaResponse,
     references: schema.arrayOf(referenceSchema),
     namespaces: schema.maybe(schema.arrayOf(schema.string())),
     originId: schema.maybe(schema.string()),

src/plugins/dashboard/server/content_management/v3/types.ts

@@ -16,6 +16,7 @@ import {
   UpdateIn,
 } from '@kbn/content-management-plugin/common';
 import { SavedObjectReference } from '@kbn/core-saved-objects-api-server';
+import { WithRequiredProperty } from '@kbn/utility-types';
 import {
   dashboardItemSchema,
   controlGroupInputSchema,
@@ -40,6 +41,7 @@ export type DashboardOptions = TypeOf<typeof optionsSchema>;
 // recognize this, so we need to manually extend the type here.
 export type DashboardPanel = Omit<TypeOf<typeof panelSchema>, 'panelConfig'> & {
   panelConfig: TypeOf<typeof panelSchema>['panelConfig'] & { [key: string]: any };
+  gridData: GridData;
 };
 export type DashboardAttributes = Omit<TypeOf<typeof dashboardAttributesSchema>, 'panels'> & {
   panels: DashboardPanel[];
@@ -52,7 +54,7 @@ export type PartialDashboardItem = Omit<DashboardItem, 'attributes' | 'reference
 };
 
 export type ControlGroupAttributes = TypeOf<typeof controlGroupInputSchema>;
-export type GridData = TypeOf<typeof gridDataSchema>;
+export type GridData = WithRequiredProperty<TypeOf<typeof gridDataSchema>, 'i'>;
 
 export type DashboardGetIn = GetIn<typeof CONTENT_ID>;
 export type DashboardGetOut = TypeOf<typeof dashboardGetResultSchema>;