Skip to content

Commit

Permalink
[Dashboards][OAS] Generate API docs for Dashboards API (#199215)
Browse files Browse the repository at this point in the history
  • Loading branch information
nickpeihl authored Dec 4, 2024
1 parent 56c38bc commit c8866e4
Show file tree
Hide file tree
Showing 8 changed files with 11,195 additions and 26 deletions.
2 changes: 1 addition & 1 deletion .buildkite/scripts/steps/checks/capture_oas_snapshot.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3,241 changes: 3,241 additions & 0 deletions oas_docs/bundle.json

Large diffs are not rendered by default.

3,241 changes: 3,241 additions & 0 deletions oas_docs/bundle.serverless.json

Large diffs are not rendered by default.

2,316 changes: 2,316 additions & 0 deletions oas_docs/output/kibana.serverless.yaml

Large diffs are not rendered by default.

2,311 changes: 2,311 additions & 0 deletions oas_docs/output/kibana.yaml

Large diffs are not rendered by default.

63 changes: 53 additions & 10 deletions src/plugins/dashboard/server/api/register_routes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ export function registerAPIRoutes({
description: TECHNICAL_PREVIEW_WARNING,
options: {
tags: ['oas-tag:Dashboards'],
availability: {
stability: 'experimental',
},
},
});

Expand All @@ -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,
Expand Down Expand Up @@ -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',
},
},
});

Expand All @@ -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,
Expand Down Expand Up @@ -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',
},
},
});

Expand All @@ -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: {
Expand Down Expand Up @@ -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',
},
},
});

Expand All @@ -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: {
Expand Down Expand Up @@ -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',
},
},
});

Expand All @@ -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.',
},
}),
}),
},
},
Expand Down
43 changes: 29 additions & 14 deletions src/plugins/dashboard/server/content_management/v3/cm_services.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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.',
Expand Down Expand Up @@ -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({
Expand Down Expand Up @@ -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({
Expand Down Expand Up @@ -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(),
Expand All @@ -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()),
Expand Down
4 changes: 3 additions & 1 deletion src/plugins/dashboard/server/content_management/v3/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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[];
Expand All @@ -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>;
Expand Down

0 comments on commit c8866e4

Please sign in to comment.