From 6edb1f5db2fa769585cc1c8ae3e630679c3f51d4 Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Thu, 11 Jul 2024 18:16:30 +0100 Subject: [PATCH 1/9] initial commit --- .../routes/alerts_filter_query/schemas/v1.ts | 10 +- .../routes/rule/apis/create/schemas/v1.ts | 8 +- .../common/routes/rule/response/schemas/v1.ts | 207 ++++++++++++++---- 3 files changed, 182 insertions(+), 43 deletions(-) diff --git a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts index 26249eb3a53f2..b31dc466eb39f 100644 --- a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts @@ -9,7 +9,7 @@ import { schema } from '@kbn/config-schema'; import { FilterStateStore } from '@kbn/es-query'; export const alertsFilterQuerySchema = schema.object({ - kql: schema.string(), + kql: schema.string({ meta: { description: 'A filter written in Kibana Query Language (KQL).' } }), filters: schema.arrayOf( schema.object({ query: schema.maybe(schema.recordOf(schema.string(), schema.any())), @@ -22,7 +22,13 @@ export const alertsFilterQuerySchema = schema.object({ ]), }) ), - }) + }), + { + meta: { + description: + 'A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the `kbn-es-query` package.', + }, + } ), dsl: schema.maybe(schema.string()), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts index cb24fe674b899..7c2eddb209383 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts @@ -183,5 +183,11 @@ export const createBodySchema = schema.object({ }); export const createParamsSchema = schema.object({ - id: schema.maybe(schema.string()), + id: schema.maybe( + schema.string({ + meta: { + description: 'The ID of the rule', + }, + }) + ), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts index e78c9b88b5d64..f9ea0b18e9e42 100644 --- a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts @@ -17,8 +17,15 @@ import { } from '../../common/constants/v1'; import { validateNotifyWhenV1 } from '../../validation'; -export const ruleParamsSchema = schema.recordOf(schema.string(), schema.maybe(schema.any())); -export const actionParamsSchema = schema.recordOf(schema.string(), schema.maybe(schema.any())); +export const ruleParamsSchema = schema.recordOf(schema.string(), schema.maybe(schema.any()), { + meta: { description: 'The parameters for the rule.' }, +}); +export const actionParamsSchema = schema.recordOf(schema.string(), schema.maybe(schema.any()), { + meta: { + description: + 'The parameters for the action, which are sent to the connector. The `params` are handled as Mustache templates and passed a default set of context.', + }, +}); export const mappedParamsSchema = schema.recordOf(schema.string(), schema.maybe(schema.any())); export const notifyWhenSchema = schema.oneOf( @@ -37,44 +44,98 @@ export const notifyWhenSchema = schema.oneOf( ); const intervalScheduleSchema = schema.object({ - interval: schema.string(), + interval: schema.string({ + meta: { description: 'The interval is specified in seconds, minutes, hours, or days.' }, + }), }); const actionFrequencySchema = schema.object({ - summary: schema.boolean(), + summary: schema.boolean({ meta: { description: 'Indicates whether the action is a summary.' } }), notify_when: notifyWhenSchema, - throttle: schema.nullable(schema.string()), + throttle: schema.nullable( + schema.string({ + meta: { + description: `The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. + NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. + If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.`, + }, + }) + ), }); const actionAlertsFilterSchema = schema.object({ query: schema.maybe(alertsFilterQuerySchemaV1), timeframe: schema.maybe( - schema.object({ - days: schema.arrayOf( - schema.oneOf([ - schema.literal(1), - schema.literal(2), - schema.literal(3), - schema.literal(4), - schema.literal(5), - schema.literal(6), - schema.literal(7), - ]) - ), - hours: schema.object({ - start: schema.string(), - end: schema.string(), - }), - timezone: schema.string(), - }) + schema.object( + { + days: schema.arrayOf( + schema.oneOf([ + schema.literal(1), + schema.literal(2), + schema.literal(3), + schema.literal(4), + schema.literal(5), + schema.literal(6), + schema.literal(7), + ]), + { + meta: { + description: + 'Defines the days of the week that the action can run, represented as an array of numbers. For example, `1` represents Monday. An empty array is equivalent to specifying all the days of the week.', + }, + } + ), + hours: schema.object({ + start: schema.string({ + meta: { + description: 'The start of the time frame in 24-hour notation (`hh:mm`).', + }, + }), + end: schema.string({ + meta: { + description: 'The end of the time frame in 24-hour notation (`hh:mm`).', + }, + }), + }), + timezone: schema.string({ + meta: { + description: + 'The ISO time zone for the `hours` values. Values such as `UTC` and `UTC+1` also work but lack built-in daylight savings time support and are not recommended.', + }, + }), + }, + { + meta: { + description: 'Defines a period that limits whether the action runs.', + }, + } + ) ), }); const actionSchema = schema.object({ - uuid: schema.maybe(schema.string()), - group: schema.maybe(schema.string()), - id: schema.string(), - connector_type_id: schema.string(), + uuid: schema.maybe( + schema.string({ + meta: { description: 'A universally unique identifier (UUID) for the action.' }, + }) + ), + group: schema.maybe( + schema.string({ + meta: { + description: + "The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to `default`.", + }, + }) + ), + id: schema.string({ + meta: { description: 'The identifier for the connector saved object.' }, + }), + connector_type_id: schema.string({ + meta: { + description: + 'The type of connector. This property appears in responses but cannot be set in requests.', + }, + }), params: actionParamsSchema, frequency: schema.maybe(actionFrequencySchema), alerts_filter: schema.maybe(actionAlertsFilterSchema), @@ -204,23 +265,89 @@ export const alertDelaySchema = schema.object( ); export const ruleResponseSchema = schema.object({ - id: schema.string(), - enabled: schema.boolean(), - name: schema.string(), - tags: schema.arrayOf(schema.string()), - rule_type_id: schema.string(), - consumer: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), + enabled: schema.boolean({ + meta: { + description: + 'Indicates whether you want to run the rule on an interval basis after it is created.', + }, + }), + name: schema.string({ + meta: { + description: ' The name of the rule.', + }, + }), + tags: schema.arrayOf( + schema.string({ + meta: { description: 'The tags for the rule.' }, + }) + ), + rule_type_id: schema.string({ + meta: { description: 'The rule type identifier.' }, + }), + consumer: schema.string({ + meta: { + description: + 'The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.', + }, + }), schedule: intervalScheduleSchema, actions: schema.arrayOf(actionSchema), params: ruleParamsSchema, mapped_params: schema.maybe(mappedParamsSchema), - scheduled_task_id: schema.maybe(schema.string()), - created_by: schema.nullable(schema.string()), - updated_by: schema.nullable(schema.string()), - created_at: schema.string(), - updated_at: schema.string(), - api_key_owner: schema.nullable(schema.string()), - api_key_created_by_user: schema.maybe(schema.nullable(schema.boolean())), + scheduled_task_id: schema.maybe( + schema.string({ + meta: { + description: 'The identifier for the scheduled task', + }, + }) + ), + created_by: schema.nullable( + schema.string({ + meta: { + description: 'The identifier for the user that created the rule.', + }, + }) + ), + updated_by: schema.nullable( + schema.string({ + meta: { + description: 'The identifier for the user that updated this rule most recently.', + }, + }) + ), + created_at: schema.string({ + meta: { + description: 'The date and time that the rule was created.', + }, + }), + updated_at: schema.string({ + meta: { + description: 'The date and time that the rule was updated most recently.', + }, + }), + api_key_owner: schema.nullable( + schema.string({ + meta: { + description: + 'The owner of the API key that is associated with the rule and used to run background tasks.', + }, + }) + ), + api_key_created_by_user: schema.maybe( + schema.nullable( + schema.boolean({ + meta: { + description: + 'Indicates whether the API key that is associated with the rule was created by the user.', + }, + }) + ) + ), throttle: schema.maybe(schema.nullable(schema.string())), mute_all: schema.boolean(), notify_when: schema.maybe(schema.nullable(notifyWhenSchema)), From 607c64d4017eb9ee7bd1a52cf5d5539739bf023f Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Mon, 15 Jul 2024 14:48:23 +0100 Subject: [PATCH 2/9] updated get, find, delete and update rule api docs --- .../routes/alerts_filter_query/schemas/v1.ts | 24 ++- .../routes/rule/apis/create/schemas/v1.ts | 2 +- .../routes/rule/apis/delete/schemas/v1.ts | 6 +- .../routes/rule/apis/find/schemas/v1.ts | 96 ++++++++-- .../common/routes/rule/apis/get/schemas/v1.ts | 6 +- .../routes/rule/apis/update/schemas/v1.ts | 167 ++++++++++++++---- .../common/routes/rule/response/schemas/v1.ts | 81 ++++++--- .../routes/rule/apis/find/find_rules_route.ts | 2 +- 8 files changed, 303 insertions(+), 81 deletions(-) diff --git a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts index b31dc466eb39f..a51073b4dae14 100644 --- a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts @@ -16,10 +16,18 @@ export const alertsFilterQuerySchema = schema.object({ meta: schema.recordOf(schema.string(), schema.any()), $state: schema.maybe( schema.object({ - store: schema.oneOf([ - schema.literal(FilterStateStore.APP_STATE), - schema.literal(FilterStateStore.GLOBAL_STATE), - ]), + store: schema.oneOf( + [ + schema.literal(FilterStateStore.APP_STATE), + schema.literal(FilterStateStore.GLOBAL_STATE), + ], + { + meta: { + description: + 'A filter is specific to an application context or whether it should be applied globally.', + }, + } + ), }) ), }), @@ -30,5 +38,11 @@ export const alertsFilterQuerySchema = schema.object({ }, } ), - dsl: schema.maybe(schema.string()), + dsl: schema.maybe( + schema.string({ + meta: { + description: 'A filter written in Elasticsearch Query Domain Specific Language (DSL).', + }, + }) + ), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts index 7c2eddb209383..e40371c90fa5a 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts @@ -186,7 +186,7 @@ export const createParamsSchema = schema.object({ id: schema.maybe( schema.string({ meta: { - description: 'The ID of the rule', + description: 'The identifier for the rule.', }, }) ), diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/delete/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/delete/schemas/v1.ts index bd79d1b7f395e..3bf8146b5ef99 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/delete/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/delete/schemas/v1.ts @@ -8,5 +8,9 @@ import { schema } from '@kbn/config-schema'; export const deleteRuleRequestParamsSchema = schema.object({ - id: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/find/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/find/schemas/v1.ts index faa483e1aef1b..1dece949a9556 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/find/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/find/schemas/v1.ts @@ -8,26 +8,98 @@ import { schema } from '@kbn/config-schema'; export const findRulesRequestQuerySchema = schema.object({ - per_page: schema.number({ defaultValue: 10, min: 0 }), - page: schema.number({ defaultValue: 1, min: 1 }), - search: schema.maybe(schema.string()), + per_page: schema.number({ + defaultValue: 10, + min: 0, + meta: { + description: 'The number of rules to return per page.', + }, + }), + page: schema.number({ + defaultValue: 1, + min: 1, + meta: { + description: 'The page number to return.', + }, + }), + search: schema.maybe( + schema.string({ + meta: { + description: + 'An Elasticsearch simple_query_string query that filters the objects in the response.', + }, + }) + ), default_search_operator: schema.oneOf([schema.literal('OR'), schema.literal('AND')], { defaultValue: 'OR', + meta: { + description: 'The default operator to use for the simple_query_string.', + }, }), - search_fields: schema.maybe(schema.oneOf([schema.arrayOf(schema.string()), schema.string()])), - sort_field: schema.maybe(schema.string()), - sort_order: schema.maybe(schema.oneOf([schema.literal('asc'), schema.literal('desc')])), + search_fields: schema.maybe( + schema.oneOf([schema.arrayOf(schema.string()), schema.string()], { + meta: { + description: 'The fields to perform the simple_query_string parsed query against.', + }, + }) + ), + sort_field: schema.maybe( + schema.string({ + meta: { + description: + 'Determines which field is used to sort the results. The field must exist in the `attributes` key of the response.', + }, + }) + ), + sort_order: schema.maybe( + schema.oneOf([schema.literal('asc'), schema.literal('desc')], { + meta: { + description: 'Determines the sort order.', + }, + }) + ), has_reference: schema.maybe( // use nullable as maybe is currently broken // in config-schema schema.nullable( - schema.object({ - type: schema.string(), - id: schema.string(), + schema.object( + { + type: schema.string(), + id: schema.string(), + }, + { + meta: { + description: + 'Filters the rules that have a relation with the reference objects with a specific type and identifier.', + }, + } + ) + ) + ), + fields: schema.maybe( + schema.arrayOf( + schema.string({ + meta: { + description: 'The fields to return in the `attributes` key of the response.', + }, + }) + ) + ), + filter: schema.maybe( + schema.string({ + meta: { + description: + 'A KQL string that you filter with an attribute from your saved object. It should look like `savedObjectType.attributes.title: "myTitle"`. However, if you used a direct attribute of a saved object, such as `updatedAt`, you must define your filter, for example, `savedObjectType.updatedAt > 2018-12-22`.', + }, + }) + ), + filter_consumers: schema.maybe( + schema.arrayOf( + schema.string({ + meta: { + description: 'List of consumers to filter.', + }, }) ) ), - fields: schema.maybe(schema.arrayOf(schema.string())), - filter: schema.maybe(schema.string()), - filter_consumers: schema.maybe(schema.arrayOf(schema.string())), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/get/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/get/schemas/v1.ts index 18ac4263043e9..292332680da20 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/get/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/get/schemas/v1.ts @@ -8,5 +8,9 @@ import { schema } from '@kbn/config-schema'; export const getRuleRequestParamsSchema = schema.object({ - id: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts index 325660530b0de..8750c00ec5eed 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts @@ -11,62 +11,153 @@ import { notifyWhenSchemaV1, alertDelaySchemaV1 } from '../../../response'; import { alertsFilterQuerySchemaV1 } from '../../../../alerts_filter_query'; export const actionFrequencySchema = schema.object({ - summary: schema.boolean(), + summary: schema.boolean({ + meta: { description: 'Indicates whether the action is a summary.' }, + }), notify_when: notifyWhenSchemaV1, - throttle: schema.nullable(schema.string({ validate: validateDurationV1 })), + throttle: schema.nullable( + schema.string({ + validate: validateDurationV1, + meta: { + description: + 'The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if `notify_when` is set to `onThrottleInterval`. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.', + }, + }) + ), }); export const actionAlertsFilterSchema = schema.object({ query: schema.maybe(alertsFilterQuerySchemaV1), timeframe: schema.maybe( - schema.object({ - days: schema.arrayOf( - schema.oneOf([ - schema.literal(1), - schema.literal(2), - schema.literal(3), - schema.literal(4), - schema.literal(5), - schema.literal(6), - schema.literal(7), - ]) - ), - hours: schema.object({ - start: schema.string({ - validate: validateHoursV1, + schema.object( + { + days: schema.arrayOf( + schema.oneOf([ + schema.literal(1), + schema.literal(2), + schema.literal(3), + schema.literal(4), + schema.literal(5), + schema.literal(6), + schema.literal(7), + ]), + { + meta: { + description: + 'Defines the days of the week that the action can run, represented as an array of numbers. For example, `1` represents Monday. An empty array is equivalent to specifying all the days of the week.', + }, + } + ), + hours: schema.object( + { + start: schema.string({ + validate: validateHoursV1, + meta: { description: 'The start of the time frame in 24-hour notation (`hh:mm`).' }, + }), + end: schema.string({ + validate: validateHoursV1, + meta: { description: 'The end of the time frame in 24-hour notation (`hh:mm`).' }, + }), + }, + { + meta: { + description: + 'Defines the range of time in a day that the action can run. If the `start` value is `00:00` and the `end` value is `24:00`, actions be generated all day.', + }, + } + ), + timezone: schema.string({ + validate: validateTimezoneV1, + meta: { + description: + 'The ISO time zone for the `hours` values. Values such as `UTC` and `UTC+1` also work but lack built-in daylight savings time support and are not recommended.', + }, }), - end: schema.string({ - validate: validateHoursV1, - }), - }), - timezone: schema.string({ validate: validateTimezoneV1 }), - }) + }, + { meta: { description: 'Defines a period that limits whether the action runs.' } } + ) ), }); -export const actionSchema = schema.object({ - group: schema.maybe(schema.string()), - id: schema.string(), - params: schema.recordOf(schema.string(), schema.any(), { defaultValue: {} }), - frequency: schema.maybe(actionFrequencySchema), - uuid: schema.maybe(schema.string()), - alerts_filter: schema.maybe(actionAlertsFilterSchema), - use_alert_data_for_template: schema.maybe(schema.boolean()), -}); +export const actionSchema = schema.object( + { + group: schema.maybe( + schema.string({ + meta: { + description: + "The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to `default`.", + }, + }) + ), + id: schema.string({ + meta: { description: 'The identifier for the connector saved object.' }, + }), + params: schema.recordOf(schema.string(), schema.any(), { + defaultValue: {}, + meta: { + description: + 'The parameters for the action, which are sent to the connector. The `params` are handled as Mustache templates and passed a default set of context.', + }, + }), + frequency: schema.maybe(actionFrequencySchema), + uuid: schema.maybe( + schema.string({ + meta: { description: 'A universally unique identifier (UUID) for the action.' }, + }) + ), + alerts_filter: schema.maybe(actionAlertsFilterSchema), + use_alert_data_for_template: schema.maybe(schema.boolean()), + }, + { + meta: { description: 'An action that runs under defined conditions.' }, + } +); export const updateBodySchema = schema.object({ - name: schema.string(), - tags: schema.arrayOf(schema.string(), { defaultValue: [] }), + name: schema.string({ + meta: { + description: + 'The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.', + }, + }), + tags: schema.arrayOf( + schema.string({ + meta: { + description: 'The tags for the rule.', + }, + }), + { defaultValue: [] } + ), schedule: schema.object({ - interval: schema.string({ validate: validateDurationV1 }), + interval: schema.string({ + validate: validateDurationV1, + meta: { description: 'The interval is specified in seconds, minutes, hours, or days.' }, + }), + }), + throttle: schema.maybe( + schema.nullable( + schema.string({ + validate: validateDurationV1, + meta: { + description: + 'Use the `throttle` property in the action `frequency` object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.', + }, + }) + ) + ), + params: schema.recordOf(schema.string(), schema.any(), { + defaultValue: {}, + meta: { description: 'The parameters for the rule.' }, }), - throttle: schema.maybe(schema.nullable(schema.string({ validate: validateDurationV1 }))), - params: schema.recordOf(schema.string(), schema.any(), { defaultValue: {} }), actions: schema.arrayOf(actionSchema, { defaultValue: [] }), notify_when: schema.maybe(schema.nullable(notifyWhenSchemaV1)), alert_delay: schema.maybe(alertDelaySchemaV1), }); export const updateParamsSchema = schema.object({ - id: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts index f9ea0b18e9e42..6582ca9b25159 100644 --- a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts @@ -143,29 +143,57 @@ const actionSchema = schema.object({ }); export const ruleExecutionStatusSchema = schema.object({ - status: schema.oneOf([ - schema.literal(ruleExecutionStatusValuesV1.OK), - schema.literal(ruleExecutionStatusValuesV1.ACTIVE), - schema.literal(ruleExecutionStatusValuesV1.ERROR), - schema.literal(ruleExecutionStatusValuesV1.WARNING), - schema.literal(ruleExecutionStatusValuesV1.PENDING), - schema.literal(ruleExecutionStatusValuesV1.UNKNOWN), - ]), - last_execution_date: schema.string(), - last_duration: schema.maybe(schema.number()), + status: schema.oneOf( + [ + schema.literal(ruleExecutionStatusValuesV1.OK), + schema.literal(ruleExecutionStatusValuesV1.ACTIVE), + schema.literal(ruleExecutionStatusValuesV1.ERROR), + schema.literal(ruleExecutionStatusValuesV1.WARNING), + schema.literal(ruleExecutionStatusValuesV1.PENDING), + schema.literal(ruleExecutionStatusValuesV1.UNKNOWN), + ], + { + meta: { + description: 'Status of rule execution.', + }, + } + ), + last_execution_date: schema.string({ + meta: { + description: 'The date and time when rule was executed last.', + }, + }), + last_duration: schema.maybe( + schema.number({ + meta: { + description: 'Duration of last execution of the rule.', + }, + }) + ), error: schema.maybe( schema.object({ - reason: schema.oneOf([ - schema.literal(ruleExecutionStatusErrorReasonV1.READ), - schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), - schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), - schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), - schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), - schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), - schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), - schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), - ]), - message: schema.string(), + reason: schema.oneOf( + [ + schema.literal(ruleExecutionStatusErrorReasonV1.READ), + schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), + schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), + schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), + schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), + schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), + schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), + schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), + ], + { + meta: { + description: 'Reason for error.', + }, + } + ), + message: schema.string({ + meta: { + description: 'error message.', + }, + }), }) ), warning: schema.maybe( @@ -348,7 +376,16 @@ export const ruleResponseSchema = schema.object({ }) ) ), - throttle: schema.maybe(schema.nullable(schema.string())), + throttle: schema.maybe( + schema.nullable( + schema.string({ + meta: { + description: + 'Deprecated in 8.13.0. Use the `throttle` property in the action `frequency` object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.', + }, + }) + ) + ), mute_all: schema.boolean(), notify_when: schema.maybe(schema.nullable(notifyWhenSchema)), muted_alert_ids: schema.arrayOf(schema.string()), diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts index 1cadb35969944..97cca44052938 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts @@ -43,7 +43,7 @@ const buildFindRulesRoute = ({ path, options: { access: 'public', - summary: `Get rules`, + summary: `Retrieves information about rules.`, }, validate: { query: findRulesRequestQuerySchemaV1, From 43e74518070e0e4e3360d03390c8d7f4e0faf074 Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Mon, 15 Jul 2024 15:51:37 +0100 Subject: [PATCH 3/9] update rule api schema --- .../routes/alerts_filter_query/schemas/v1.ts | 21 +- .../routes/rule/apis/create/schemas/v1.ts | 8 +- .../routes/rule/apis/update/schemas/v1.ts | 8 +- .../common/routes/rule/response/schemas/v1.ts | 277 ++++-------------- 4 files changed, 93 insertions(+), 221 deletions(-) diff --git a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts index a51073b4dae14..324b927f40af8 100644 --- a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts @@ -12,8 +12,25 @@ export const alertsFilterQuerySchema = schema.object({ kql: schema.string({ meta: { description: 'A filter written in Kibana Query Language (KQL).' } }), filters: schema.arrayOf( schema.object({ - query: schema.maybe(schema.recordOf(schema.string(), schema.any())), - meta: schema.recordOf(schema.string(), schema.any()), + query: schema.maybe( + schema.recordOf( + schema.string(), + schema.any({ + meta: { + description: 'A query for the filter.', + }, + }) + ) + ), + meta: schema.recordOf( + schema.string(), + schema.any({ + meta: { + description: + 'An object with fields such as "controlledBy", "disabled", "field", "group", "index", "isMultiIndex", "key", "negate", "params", "type", "value"', + }, + }) + ), $state: schema.maybe( schema.object({ store: schema.oneOf( diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts index e40371c90fa5a..57e92eb284e5e 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts @@ -114,7 +114,13 @@ export const actionSchema = schema.object( }) ), alerts_filter: schema.maybe(actionAlertsFilterSchema), - use_alert_data_for_template: schema.maybe(schema.boolean()), + use_alert_data_for_template: schema.maybe( + schema.boolean({ + meta: { + description: 'Indicates whether to use alert data as template or not.', + }, + }) + ), }, { meta: { description: 'An action that runs under defined conditions.' }, diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts index 8750c00ec5eed..4e3c3b28964a8 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts @@ -106,7 +106,13 @@ export const actionSchema = schema.object( }) ), alerts_filter: schema.maybe(actionAlertsFilterSchema), - use_alert_data_for_template: schema.maybe(schema.boolean()), + use_alert_data_for_template: schema.maybe( + schema.boolean({ + meta: { + description: 'Indicates whether to use alert data as template or not.', + }, + }) + ), }, { meta: { description: 'An action that runs under defined conditions.' }, diff --git a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts index 6582ca9b25159..285dd23e442bf 100644 --- a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts @@ -44,98 +44,44 @@ export const notifyWhenSchema = schema.oneOf( ); const intervalScheduleSchema = schema.object({ - interval: schema.string({ - meta: { description: 'The interval is specified in seconds, minutes, hours, or days.' }, - }), + interval: schema.string(), }); const actionFrequencySchema = schema.object({ - summary: schema.boolean({ meta: { description: 'Indicates whether the action is a summary.' } }), + summary: schema.boolean(), notify_when: notifyWhenSchema, - throttle: schema.nullable( - schema.string({ - meta: { - description: `The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. - NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. - If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.`, - }, - }) - ), + throttle: schema.nullable(schema.string()), }); const actionAlertsFilterSchema = schema.object({ query: schema.maybe(alertsFilterQuerySchemaV1), timeframe: schema.maybe( - schema.object( - { - days: schema.arrayOf( - schema.oneOf([ - schema.literal(1), - schema.literal(2), - schema.literal(3), - schema.literal(4), - schema.literal(5), - schema.literal(6), - schema.literal(7), - ]), - { - meta: { - description: - 'Defines the days of the week that the action can run, represented as an array of numbers. For example, `1` represents Monday. An empty array is equivalent to specifying all the days of the week.', - }, - } - ), - hours: schema.object({ - start: schema.string({ - meta: { - description: 'The start of the time frame in 24-hour notation (`hh:mm`).', - }, - }), - end: schema.string({ - meta: { - description: 'The end of the time frame in 24-hour notation (`hh:mm`).', - }, - }), - }), - timezone: schema.string({ - meta: { - description: - 'The ISO time zone for the `hours` values. Values such as `UTC` and `UTC+1` also work but lack built-in daylight savings time support and are not recommended.', - }, - }), - }, - { - meta: { - description: 'Defines a period that limits whether the action runs.', - }, - } - ) + schema.object({ + days: schema.arrayOf( + schema.oneOf([ + schema.literal(1), + schema.literal(2), + schema.literal(3), + schema.literal(4), + schema.literal(5), + schema.literal(6), + schema.literal(7), + ]) + ), + hours: schema.object({ + start: schema.string(), + end: schema.string(), + }), + timezone: schema.string(), + }) ), }); const actionSchema = schema.object({ - uuid: schema.maybe( - schema.string({ - meta: { description: 'A universally unique identifier (UUID) for the action.' }, - }) - ), - group: schema.maybe( - schema.string({ - meta: { - description: - "The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to `default`.", - }, - }) - ), - id: schema.string({ - meta: { description: 'The identifier for the connector saved object.' }, - }), - connector_type_id: schema.string({ - meta: { - description: - 'The type of connector. This property appears in responses but cannot be set in requests.', - }, - }), + uuid: schema.maybe(schema.string()), + group: schema.maybe(schema.string()), + id: schema.string(), + connector_type_id: schema.string(), params: actionParamsSchema, frequency: schema.maybe(actionFrequencySchema), alerts_filter: schema.maybe(actionAlertsFilterSchema), @@ -143,57 +89,29 @@ const actionSchema = schema.object({ }); export const ruleExecutionStatusSchema = schema.object({ - status: schema.oneOf( - [ - schema.literal(ruleExecutionStatusValuesV1.OK), - schema.literal(ruleExecutionStatusValuesV1.ACTIVE), - schema.literal(ruleExecutionStatusValuesV1.ERROR), - schema.literal(ruleExecutionStatusValuesV1.WARNING), - schema.literal(ruleExecutionStatusValuesV1.PENDING), - schema.literal(ruleExecutionStatusValuesV1.UNKNOWN), - ], - { - meta: { - description: 'Status of rule execution.', - }, - } - ), - last_execution_date: schema.string({ - meta: { - description: 'The date and time when rule was executed last.', - }, - }), - last_duration: schema.maybe( - schema.number({ - meta: { - description: 'Duration of last execution of the rule.', - }, - }) - ), + status: schema.oneOf([ + schema.literal(ruleExecutionStatusValuesV1.OK), + schema.literal(ruleExecutionStatusValuesV1.ACTIVE), + schema.literal(ruleExecutionStatusValuesV1.ERROR), + schema.literal(ruleExecutionStatusValuesV1.WARNING), + schema.literal(ruleExecutionStatusValuesV1.PENDING), + schema.literal(ruleExecutionStatusValuesV1.UNKNOWN), + ]), + last_execution_date: schema.string(), + last_duration: schema.maybe(schema.number()), error: schema.maybe( schema.object({ - reason: schema.oneOf( - [ - schema.literal(ruleExecutionStatusErrorReasonV1.READ), - schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), - schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), - schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), - schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), - schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), - schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), - schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), - ], - { - meta: { - description: 'Reason for error.', - }, - } - ), - message: schema.string({ - meta: { - description: 'error message.', - }, - }), + reason: schema.oneOf([ + schema.literal(ruleExecutionStatusErrorReasonV1.READ), + schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), + schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), + schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), + schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), + schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), + schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), + schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), + ]), + message: schema.string(), }) ), warning: schema.maybe( @@ -293,99 +211,24 @@ export const alertDelaySchema = schema.object( ); export const ruleResponseSchema = schema.object({ - id: schema.string({ - meta: { - description: 'The identifier for the rule.', - }, - }), - enabled: schema.boolean({ - meta: { - description: - 'Indicates whether you want to run the rule on an interval basis after it is created.', - }, - }), - name: schema.string({ - meta: { - description: ' The name of the rule.', - }, - }), - tags: schema.arrayOf( - schema.string({ - meta: { description: 'The tags for the rule.' }, - }) - ), - rule_type_id: schema.string({ - meta: { description: 'The rule type identifier.' }, - }), - consumer: schema.string({ - meta: { - description: - 'The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.', - }, - }), + id: schema.string(), + enabled: schema.boolean(), + name: schema.string(), + tags: schema.arrayOf(schema.string()), + rule_type_id: schema.string(), + consumer: schema.string(), schedule: intervalScheduleSchema, actions: schema.arrayOf(actionSchema), params: ruleParamsSchema, mapped_params: schema.maybe(mappedParamsSchema), - scheduled_task_id: schema.maybe( - schema.string({ - meta: { - description: 'The identifier for the scheduled task', - }, - }) - ), - created_by: schema.nullable( - schema.string({ - meta: { - description: 'The identifier for the user that created the rule.', - }, - }) - ), - updated_by: schema.nullable( - schema.string({ - meta: { - description: 'The identifier for the user that updated this rule most recently.', - }, - }) - ), - created_at: schema.string({ - meta: { - description: 'The date and time that the rule was created.', - }, - }), - updated_at: schema.string({ - meta: { - description: 'The date and time that the rule was updated most recently.', - }, - }), - api_key_owner: schema.nullable( - schema.string({ - meta: { - description: - 'The owner of the API key that is associated with the rule and used to run background tasks.', - }, - }) - ), - api_key_created_by_user: schema.maybe( - schema.nullable( - schema.boolean({ - meta: { - description: - 'Indicates whether the API key that is associated with the rule was created by the user.', - }, - }) - ) - ), - throttle: schema.maybe( - schema.nullable( - schema.string({ - meta: { - description: - 'Deprecated in 8.13.0. Use the `throttle` property in the action `frequency` object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.', - }, - }) - ) - ), + scheduled_task_id: schema.maybe(schema.string()), + created_by: schema.nullable(schema.string()), + updated_by: schema.nullable(schema.string()), + created_at: schema.string(), + updated_at: schema.string(), + api_key_owner: schema.nullable(schema.string()), + api_key_created_by_user: schema.maybe(schema.nullable(schema.boolean())), + throttle: schema.maybe(schema.nullable(schema.string())), mute_all: schema.boolean(), notify_when: schema.maybe(schema.nullable(notifyWhenSchema)), muted_alert_ids: schema.arrayOf(schema.string()), From ee159ae6a452e718ac792f23753f4ed190b9bfde Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Tue, 16 Jul 2024 14:36:03 +0100 Subject: [PATCH 4/9] added response details to OAS --- .../routes/r_rule/response/schemas/v1.ts | 185 ++++- .../common/routes/rule/response/schemas/v1.ts | 643 ++++++++++++++---- .../rule/apis/create/create_rule_route.ts | 13 +- .../routes/rule/apis/find/find_rules_route.ts | 11 +- .../routes/rule/apis/get/get_rule_route.ts | 11 +- .../rule/apis/update/update_rule_route.ts | 13 +- 6 files changed, 697 insertions(+), 179 deletions(-) diff --git a/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts index 13cb7cb3824f4..5098b9b97971c 100644 --- a/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts @@ -8,40 +8,157 @@ import { schema } from '@kbn/config-schema'; export const rRuleResponseSchema = schema.object({ - dtstart: schema.string(), - tzid: schema.string(), + dtstart: schema.string({ + meta: { + description: 'Rule start date as per UTC.', + }, + }), + tzid: schema.string({ + meta: { + description: 'Indicates timezone.', + }, + }), freq: schema.maybe( - schema.oneOf([ - schema.literal(0), - schema.literal(1), - schema.literal(2), - schema.literal(3), - schema.literal(4), - schema.literal(5), - schema.literal(6), - ]) - ), - until: schema.maybe(schema.string()), - count: schema.maybe(schema.number()), - interval: schema.maybe(schema.number()), + schema.oneOf( + [ + schema.literal(0), + schema.literal(1), + schema.literal(2), + schema.literal(3), + schema.literal(4), + schema.literal(5), + schema.literal(6), + ], + { + meta: { + description: + 'Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.', + }, + } + ) + ), + until: schema.maybe( + schema.string({ + meta: { + description: 'Recur the rule until this date.', + }, + }) + ), + count: schema.maybe( + schema.number({ + meta: { + description: 'Number of times the rule should recur until it stops.', + }, + }) + ), + interval: schema.maybe( + schema.number({ + meta: { + description: + 'Indicates the interval of frequency, e.g. 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.', + }, + }) + ), wkst: schema.maybe( - schema.oneOf([ - schema.literal('MO'), - schema.literal('TU'), - schema.literal('WE'), - schema.literal('TH'), - schema.literal('FR'), - schema.literal('SA'), - schema.literal('SU'), - ]) - ), - byweekday: schema.maybe(schema.arrayOf(schema.oneOf([schema.string(), schema.number()]))), - bymonth: schema.maybe(schema.arrayOf(schema.number())), - bysetpos: schema.maybe(schema.arrayOf(schema.number())), - bymonthday: schema.maybe(schema.arrayOf(schema.number())), - byyearday: schema.maybe(schema.arrayOf(schema.number())), - byweekno: schema.maybe(schema.arrayOf(schema.number())), - byhour: schema.maybe(schema.arrayOf(schema.number())), - byminute: schema.maybe(schema.arrayOf(schema.number())), - bysecond: schema.maybe(schema.arrayOf(schema.number())), + schema.oneOf( + [ + schema.literal('MO'), + schema.literal('TU'), + schema.literal('WE'), + schema.literal('TH'), + schema.literal('FR'), + schema.literal('SA'), + schema.literal('SU'), + ], + { + meta: { + description: + 'Indicates the start of week, defaults to Monday. The following, if not provided, will be automatically derived from the dtstart.', + }, + } + ) + ), + byweekday: schema.maybe( + schema.arrayOf( + schema.oneOf([schema.string(), schema.number()], { + meta: { + description: + 'Indicates day(s) of the week to recur, OR nth-day-of-month strings, e.g. "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which will get internally converted to a byweekday/bysetpos combination.', + }, + }) + ) + ), + bymonth: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: 'Indicates month(s) of the year that this rule should recur.', + }, + }) + ) + ), + bysetpos: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: + 'Indicates positive or negative integer affecting nth day of the month, eg -2 combined with byweekday of FR is 2nd to last Friday of the month. Best not to set this manually and just use byweekday.', + }, + }) + ) + ), + bymonthday: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: 'Indicates day(s) of the month to recur.', + }, + }) + ) + ), + byyearday: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: 'Indicates day(s) of the year that this rule should recur.', + }, + }) + ) + ), + byweekno: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: 'Indicates number of the week hour(s) to recur.', + }, + }) + ) + ), + byhour: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: 'Indicates hour(s) of the day to recur.', + }, + }) + ) + ), + byminute: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: 'Indicates Minute(s) of the hour to recur.', + }, + }) + ) + ), + bysecond: schema.maybe( + schema.arrayOf( + schema.number({ + meta: { + description: 'Indicates seconds(s) of the day to recur.', + }, + }) + ) + ), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts index 285dd23e442bf..af419a4a36e21 100644 --- a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts @@ -26,7 +26,10 @@ export const actionParamsSchema = schema.recordOf(schema.string(), schema.maybe( 'The parameters for the action, which are sent to the connector. The `params` are handled as Mustache templates and passed a default set of context.', }, }); -export const mappedParamsSchema = schema.recordOf(schema.string(), schema.maybe(schema.any())); +export const mappedParamsSchema = schema.recordOf( + schema.string({ meta: { description: 'The mapped parameters for the rule.' } }), + schema.maybe(schema.any()) +); export const notifyWhenSchema = schema.oneOf( [ @@ -44,156 +47,397 @@ export const notifyWhenSchema = schema.oneOf( ); const intervalScheduleSchema = schema.object({ - interval: schema.string(), + interval: schema.string({ + meta: { description: 'The interval is specified in seconds, minutes, hours, or days.' }, + }), }); const actionFrequencySchema = schema.object({ - summary: schema.boolean(), + summary: schema.boolean({ meta: { description: 'Indicates whether the action is a summary.' } }), notify_when: notifyWhenSchema, - throttle: schema.nullable(schema.string()), -}); - -const actionAlertsFilterSchema = schema.object({ - query: schema.maybe(alertsFilterQuerySchemaV1), - timeframe: schema.maybe( - schema.object({ - days: schema.arrayOf( - schema.oneOf([ - schema.literal(1), - schema.literal(2), - schema.literal(3), - schema.literal(4), - schema.literal(5), - schema.literal(6), - schema.literal(7), - ]) - ), - hours: schema.object({ - start: schema.string(), - end: schema.string(), - }), - timezone: schema.string(), + throttle: schema.nullable( + schema.string({ + meta: { + description: `The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.`, + }, }) ), }); +const actionAlertsFilterSchema = schema.object( + { + query: schema.maybe(alertsFilterQuerySchemaV1), + timeframe: schema.maybe( + schema.object({ + days: schema.arrayOf( + schema.oneOf([ + schema.literal(1), + schema.literal(2), + schema.literal(3), + schema.literal(4), + schema.literal(5), + schema.literal(6), + schema.literal(7), + ]), + { + meta: { + description: + 'Defines the days of the week that the action can run, represented as an array of numbers. For example, `1` represents Monday. An empty array is equivalent to specifying all the days of the week.', + }, + } + ), + hours: schema.object({ + start: schema.string({ + meta: { + description: 'The start of the time frame in 24-hour notation (`hh:mm`).', + }, + }), + end: schema.string({ + meta: { + description: 'The end of the time frame in 24-hour notation (`hh:mm`).', + }, + }), + }), + timezone: schema.string({ + meta: { + description: + 'The ISO time zone for the `hours` values. Values such as `UTC` and `UTC+1` also work but lack built-in daylight savings time support and are not recommended.', + }, + }), + }) + ), + }, + { + meta: { + description: 'Defines a period that limits whether the action runs.', + }, + } +); + const actionSchema = schema.object({ - uuid: schema.maybe(schema.string()), - group: schema.maybe(schema.string()), - id: schema.string(), - connector_type_id: schema.string(), + uuid: schema.maybe( + schema.string({ + meta: { description: 'A universally unique identifier (UUID) for the action.' }, + }) + ), + group: schema.maybe( + schema.string({ + meta: { + description: + "The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to `default`.", + }, + }) + ), + id: schema.string({ + meta: { description: 'The identifier for the connector saved object.' }, + }), + connector_type_id: schema.string({ + meta: { + description: + 'The type of connector. This property appears in responses but cannot be set in requests.', + }, + }), params: actionParamsSchema, frequency: schema.maybe(actionFrequencySchema), alerts_filter: schema.maybe(actionAlertsFilterSchema), - use_alert_data_for_template: schema.maybe(schema.boolean()), + use_alert_data_for_template: schema.maybe( + schema.boolean({ + meta: { description: 'Indicates whether to use alert data as template or not.' }, + }) + ), }); export const ruleExecutionStatusSchema = schema.object({ - status: schema.oneOf([ - schema.literal(ruleExecutionStatusValuesV1.OK), - schema.literal(ruleExecutionStatusValuesV1.ACTIVE), - schema.literal(ruleExecutionStatusValuesV1.ERROR), - schema.literal(ruleExecutionStatusValuesV1.WARNING), - schema.literal(ruleExecutionStatusValuesV1.PENDING), - schema.literal(ruleExecutionStatusValuesV1.UNKNOWN), - ]), - last_execution_date: schema.string(), - last_duration: schema.maybe(schema.number()), + status: schema.oneOf( + [ + schema.literal(ruleExecutionStatusValuesV1.OK), + schema.literal(ruleExecutionStatusValuesV1.ACTIVE), + schema.literal(ruleExecutionStatusValuesV1.ERROR), + schema.literal(ruleExecutionStatusValuesV1.WARNING), + schema.literal(ruleExecutionStatusValuesV1.PENDING), + schema.literal(ruleExecutionStatusValuesV1.UNKNOWN), + ], + { + meta: { + description: 'Status of rule execution.', + }, + } + ), + last_execution_date: schema.string({ + meta: { + description: 'The date and time when rule was executed last.', + }, + }), + last_duration: schema.maybe( + schema.number({ + meta: { + description: 'Duration of last execution of the rule.', + }, + }) + ), error: schema.maybe( schema.object({ - reason: schema.oneOf([ - schema.literal(ruleExecutionStatusErrorReasonV1.READ), - schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), - schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), - schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), - schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), - schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), - schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), - schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), - ]), - message: schema.string(), + reason: schema.oneOf( + [ + schema.literal(ruleExecutionStatusErrorReasonV1.READ), + schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), + schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), + schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), + schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), + schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), + schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), + schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), + ], + { + meta: { + description: 'Reason for error.', + }, + } + ), + message: schema.string({ + meta: { + description: 'Error message.', + }, + }), }) ), warning: schema.maybe( schema.object({ - reason: schema.oneOf([ - schema.literal(ruleExecutionStatusWarningReasonV1.MAX_EXECUTABLE_ACTIONS), - schema.literal(ruleExecutionStatusWarningReasonV1.MAX_ALERTS), - schema.literal(ruleExecutionStatusWarningReasonV1.MAX_QUEUED_ACTIONS), - ]), - message: schema.string(), + reason: schema.oneOf( + [ + schema.literal(ruleExecutionStatusWarningReasonV1.MAX_EXECUTABLE_ACTIONS), + schema.literal(ruleExecutionStatusWarningReasonV1.MAX_ALERTS), + schema.literal(ruleExecutionStatusWarningReasonV1.MAX_QUEUED_ACTIONS), + ], + { + meta: { + description: 'Reason for warning.', + }, + } + ), + message: schema.string({ + meta: { + description: 'Warning message.', + }, + }), }) ), }); export const ruleLastRunSchema = schema.object({ - outcome: schema.oneOf([ - schema.literal(ruleLastRunOutcomeValuesV1.SUCCEEDED), - schema.literal(ruleLastRunOutcomeValuesV1.WARNING), - schema.literal(ruleLastRunOutcomeValuesV1.FAILED), - ]), - outcome_order: schema.maybe(schema.number()), + outcome: schema.oneOf( + [ + schema.literal(ruleLastRunOutcomeValuesV1.SUCCEEDED), + schema.literal(ruleLastRunOutcomeValuesV1.WARNING), + schema.literal(ruleLastRunOutcomeValuesV1.FAILED), + ], + { + meta: { + description: + 'Outcome of last run of the rule. Value could be succeeded, warning or failed.', + }, + } + ), + outcome_order: schema.maybe( + schema.number({ + meta: { + description: 'Order of the outcome.', + }, + }) + ), warning: schema.maybe( schema.nullable( - schema.oneOf([ - schema.literal(ruleExecutionStatusErrorReasonV1.READ), - schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), - schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), - schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), - schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), - schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), - schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), - schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), - schema.literal(ruleExecutionStatusWarningReasonV1.MAX_EXECUTABLE_ACTIONS), - schema.literal(ruleExecutionStatusWarningReasonV1.MAX_ALERTS), - schema.literal(ruleExecutionStatusWarningReasonV1.MAX_QUEUED_ACTIONS), - ]) + schema.oneOf( + [ + schema.literal(ruleExecutionStatusErrorReasonV1.READ), + schema.literal(ruleExecutionStatusErrorReasonV1.DECRYPT), + schema.literal(ruleExecutionStatusErrorReasonV1.EXECUTE), + schema.literal(ruleExecutionStatusErrorReasonV1.UNKNOWN), + schema.literal(ruleExecutionStatusErrorReasonV1.LICENSE), + schema.literal(ruleExecutionStatusErrorReasonV1.TIMEOUT), + schema.literal(ruleExecutionStatusErrorReasonV1.DISABLED), + schema.literal(ruleExecutionStatusErrorReasonV1.VALIDATE), + schema.literal(ruleExecutionStatusWarningReasonV1.MAX_EXECUTABLE_ACTIONS), + schema.literal(ruleExecutionStatusWarningReasonV1.MAX_ALERTS), + schema.literal(ruleExecutionStatusWarningReasonV1.MAX_QUEUED_ACTIONS), + ], + { + meta: { + description: 'Warning of last rule execution.', + }, + } + ) + ) + ), + outcome_msg: schema.maybe( + schema.nullable( + schema.arrayOf( + schema.string({ + meta: { + description: 'Outcome message generated during last rule run.', + }, + }) + ) ) ), - outcome_msg: schema.maybe(schema.nullable(schema.arrayOf(schema.string()))), alerts_count: schema.object({ - active: schema.maybe(schema.nullable(schema.number())), - new: schema.maybe(schema.nullable(schema.number())), - recovered: schema.maybe(schema.nullable(schema.number())), - ignored: schema.maybe(schema.nullable(schema.number())), + active: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: 'Number of active alerts during last run.', + }, + }) + ) + ), + new: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: 'Number of new alerts during last run.', + }, + }) + ) + ), + recovered: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: 'Number of recovered alerts during last run.', + }, + }) + ) + ), + ignored: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: 'Number of ignore alerts during last run.', + }, + }) + ) + ), }), }); -export const monitoringSchema = schema.object({ - run: schema.object({ - history: schema.arrayOf( - schema.object({ - success: schema.boolean(), - timestamp: schema.number(), - duration: schema.maybe(schema.number()), - outcome: schema.maybe(ruleLastRunSchema), - }) +export const monitoringSchema = schema.object( + { + run: schema.object( + { + history: schema.arrayOf( + schema.object({ + success: schema.boolean({ + meta: { description: 'Indicates whether the rule run was success or not.' }, + }), + timestamp: schema.number({ meta: { description: 'Time of rule run.' } }), + duration: schema.maybe( + schema.number({ meta: { description: 'Duration of the rule run.' } }) + ), + outcome: schema.maybe(ruleLastRunSchema), + }), + { meta: { description: 'History of the rule run.' } } + ), + calculated_metrics: schema.object({ + p50: schema.maybe(schema.number()), + p95: schema.maybe(schema.number()), + p99: schema.maybe(schema.number()), + success_ratio: schema.number(), + }), + last_run: schema.object({ + timestamp: schema.string({ + meta: { description: 'Time when the rule was run last.' }, + }), + metrics: schema.object({ + duration: schema.maybe( + schema.number({ + meta: { description: 'Duration of last rule run.' }, + }) + ), + total_search_duration_ms: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: + 'Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response.', + }, + }) + ) + ), + total_indexing_duration_ms: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: + 'Total time spent indexing documents during last rule run in milliseconds.', + }, + }) + ) + ), + total_alerts_detected: schema.maybe( + schema.nullable( + schema.number({ + meta: { description: 'Total number of alerts detected during last rule run.' }, + }) + ) + ), + total_alerts_created: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: 'Total number of alerts created during last rule run.', + }, + }) + ) + ), + gap_duration_s: schema.maybe( + schema.nullable( + schema.number({ + meta: { + description: 'Duration in seconds of rule run gap.', + }, + }) + ) + ), + }), + }), + }, + { + meta: { + description: 'Rule run details.', + }, + } ), - calculated_metrics: schema.object({ - p50: schema.maybe(schema.number()), - p95: schema.maybe(schema.number()), - p99: schema.maybe(schema.number()), - success_ratio: schema.number(), - }), - last_run: schema.object({ - timestamp: schema.string(), - metrics: schema.object({ - duration: schema.maybe(schema.number()), - total_search_duration_ms: schema.maybe(schema.nullable(schema.number())), - total_indexing_duration_ms: schema.maybe(schema.nullable(schema.number())), - total_alerts_detected: schema.maybe(schema.nullable(schema.number())), - total_alerts_created: schema.maybe(schema.nullable(schema.number())), - gap_duration_s: schema.maybe(schema.nullable(schema.number())), - }), - }), - }), -}); + }, + { + meta: { + description: 'Monitoring details of the rule.', + }, + } +); export const ruleSnoozeScheduleSchema = schema.object({ - id: schema.maybe(schema.string()), - duration: schema.number(), + id: schema.maybe( + schema.string({ + meta: { + description: 'Identifier of the rule snooze schedule.', + }, + }) + ), + duration: schema.number({ + meta: { + description: 'Duration of the rule snooze schedule.', + }, + }), rRule: rRuleResponseSchemaV1, - skipRecurrences: schema.maybe(schema.arrayOf(schema.string())), + skipRecurrences: schema.maybe( + schema.arrayOf( + schema.string({ + meta: { + description: 'Skips recurrence of rule on this date.', + }, + }) + ) + ), }); export const alertDelaySchema = schema.object( @@ -211,37 +455,166 @@ export const alertDelaySchema = schema.object( ); export const ruleResponseSchema = schema.object({ - id: schema.string(), - enabled: schema.boolean(), - name: schema.string(), - tags: schema.arrayOf(schema.string()), - rule_type_id: schema.string(), - consumer: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), + enabled: schema.boolean({ + meta: { + description: + 'Indicates whether you want to run the rule on an interval basis after it is created.', + }, + }), + name: schema.string({ + meta: { + description: ' The name of the rule.', + }, + }), + tags: schema.arrayOf( + schema.string({ + meta: { description: 'The tags for the rule.' }, + }) + ), + rule_type_id: schema.string({ + meta: { description: 'The rule type identifier.' }, + }), + consumer: schema.string({ + meta: { + description: + 'The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.', + }, + }), schedule: intervalScheduleSchema, actions: schema.arrayOf(actionSchema), params: ruleParamsSchema, mapped_params: schema.maybe(mappedParamsSchema), - scheduled_task_id: schema.maybe(schema.string()), - created_by: schema.nullable(schema.string()), - updated_by: schema.nullable(schema.string()), - created_at: schema.string(), - updated_at: schema.string(), - api_key_owner: schema.nullable(schema.string()), - api_key_created_by_user: schema.maybe(schema.nullable(schema.boolean())), - throttle: schema.maybe(schema.nullable(schema.string())), - mute_all: schema.boolean(), + scheduled_task_id: schema.maybe( + schema.string({ + meta: { + description: 'Identifier of the scheduled task.', + }, + }) + ), + created_by: schema.nullable( + schema.string({ + meta: { + description: 'The identifier for the user that created the rule.', + }, + }) + ), + updated_by: schema.nullable( + schema.string({ + meta: { + description: 'The identifier for the user that updated this rule most recently.', + }, + }) + ), + created_at: schema.string({ + meta: { + description: 'The date and time that the rule was created.', + }, + }), + updated_at: schema.string({ + meta: { + description: 'The date and time that the rule was updated most recently.', + }, + }), + api_key_owner: schema.nullable( + schema.string({ + meta: { + description: + 'The owner of the API key that is associated with the rule and used to run background tasks.', + }, + }) + ), + api_key_created_by_user: schema.maybe( + schema.nullable( + schema.boolean({ + meta: { + description: + 'Indicates whether the API key that is associated with the rule was created by the user.', + }, + }) + ) + ), + throttle: schema.maybe( + schema.nullable( + schema.string({ + meta: { + description: + 'Deprecated in 8.13.0. Use the `throttle` property in the action `frequency` object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.', + }, + }) + ) + ), + mute_all: schema.boolean({ + meta: { + description: 'Indicates whether all alerts are muted or not.', + }, + }), notify_when: schema.maybe(schema.nullable(notifyWhenSchema)), - muted_alert_ids: schema.arrayOf(schema.string()), + muted_alert_ids: schema.arrayOf( + schema.string({ + meta: { + description: 'List of identifiers of muted alerts. ', + }, + }) + ), execution_status: ruleExecutionStatusSchema, monitoring: schema.maybe(monitoringSchema), snooze_schedule: schema.maybe(schema.arrayOf(ruleSnoozeScheduleSchema)), - active_snoozes: schema.maybe(schema.arrayOf(schema.string())), - is_snoozed_until: schema.maybe(schema.nullable(schema.string())), + active_snoozes: schema.maybe( + schema.arrayOf( + schema.string({ + meta: { + description: `List of rule's active snoozes.`, + }, + }) + ) + ), + is_snoozed_until: schema.maybe( + schema.nullable( + schema.string({ + meta: { + description: 'Date until when rule is snoozed.', + }, + }) + ) + ), last_run: schema.maybe(schema.nullable(ruleLastRunSchema)), - next_run: schema.maybe(schema.nullable(schema.string())), - revision: schema.number(), - running: schema.maybe(schema.nullable(schema.boolean())), - view_in_app_relative_url: schema.maybe(schema.nullable(schema.string())), + next_run: schema.maybe( + schema.nullable( + schema.string({ + meta: { + description: 'Date and time of the next run of the rule.', + }, + }) + ) + ), + revision: schema.number({ + meta: { + description: 'The rule revision number.', + }, + }), + running: schema.maybe( + schema.nullable( + schema.boolean({ + meta: { + description: 'Indicates whether the rule is running.', + }, + }) + ) + ), + view_in_app_relative_url: schema.maybe( + schema.nullable( + schema.string({ + meta: { + description: 'Relative URL to view rule in the app.', + }, + }) + ) + ), alert_delay: schema.maybe(alertDelaySchema), }); diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts index 5bb1eec92de26..cc01599d6b2c1 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts @@ -22,7 +22,7 @@ import { createBodySchemaV1, createParamsSchemaV1, } from '../../../../../common/routes/rule/apis/create'; -import type { RuleParamsV1 } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; import { Rule } from '../../../../application/rule/types'; import { transformCreateBodyV1 } from './transforms'; import { transformRuleToRuleResponseV1 } from '../../transforms'; @@ -37,8 +37,15 @@ export const createRuleRoute = ({ router, licenseState, usageCounter }: RouteOpt summary: `Create a rule`, }, validate: { - body: createBodySchemaV1, - params: createParamsSchemaV1, + request: { + body: createBodySchemaV1, + params: createParamsSchemaV1, + }, + response: { + 200: { + body: () => ruleResponseSchema, + }, + }, }, }, handleDisabledApiKeysError( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts index 97cca44052938..c07d9dc5e0515 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts @@ -14,7 +14,7 @@ import type { FindRulesRequestQueryV1, FindRulesResponseV1, } from '../../../../../common/routes/rule/apis/find'; -import type { RuleParamsV1 } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; import { AlertingRequestHandlerContext, BASE_ALERTING_API_PATH, @@ -46,7 +46,14 @@ const buildFindRulesRoute = ({ summary: `Retrieves information about rules.`, }, validate: { - query: findRulesRequestQuerySchemaV1, + request: { + query: findRulesRequestQuerySchemaV1, + }, + response: { + 200: { + body: () => ruleResponseSchema, + }, + }, }, }, router.handleLegacyErrors( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts index e08c81a1d2e5c..550a4d2c88df3 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts @@ -8,7 +8,7 @@ import { IRouter, RouteConfigOptions, RouteMethod } from '@kbn/core/server'; import { ILicenseState } from '../../../../lib'; import { verifyAccessAndContext } from '../../../lib'; -import type { RuleParamsV1 } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; import { Rule } from '../../../../application/rule/types'; import { AlertingRequestHandlerContext, @@ -42,7 +42,14 @@ const buildGetRuleRoute = ({ path, options, validate: { - params: getRuleRequestParamsSchemaV1, + request: { + params: getRuleRequestParamsSchemaV1, + }, + response: { + 200: { + body: () => ruleResponseSchema, + }, + }, }, }, router.handleLegacyErrors( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts index f13d3ac9ee31b..bd0a447302eb6 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts @@ -17,7 +17,7 @@ import { updateBodySchemaV1, updateParamsSchemaV1, } from '../../../../../common/routes/rule/apis/update'; -import type { RuleParamsV1 } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; import { AlertingRequestHandlerContext, BASE_ALERTING_API_PATH } from '../../../../types'; import { Rule } from '../../../../application/rule/types'; import { transformUpdateBodyV1 } from './transforms'; @@ -36,8 +36,15 @@ export const updateRuleRoute = ( summary: `Update a rule`, }, validate: { - body: updateBodySchemaV1, - params: updateParamsSchemaV1, + request: { + body: updateBodySchemaV1, + params: updateParamsSchemaV1, + }, + response: { + 200: { + body: () => ruleResponseSchema, + }, + }, }, }, handleDisabledApiKeysError( From c235096224c4e9e56d0641a431a6135df7aae496 Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Tue, 16 Jul 2024 14:52:12 +0100 Subject: [PATCH 5/9] update mute and unmute alert APIs --- .../common/routes/rule/apis/mute_alert/schemas/v1.ts | 12 ++++++++++-- .../plugins/alerting/server/routes/unmute_alert.ts | 12 ++++++++++-- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/mute_alert/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/mute_alert/schemas/v1.ts index 3cfe34de957e2..8a732dacb97a3 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/mute_alert/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/mute_alert/schemas/v1.ts @@ -8,6 +8,14 @@ import { schema } from '@kbn/config-schema'; export const muteAlertParamsSchema = schema.object({ - rule_id: schema.string(), - alert_id: schema.string(), + rule_id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), + alert_id: schema.string({ + meta: { + description: 'The identifier for the alert.', + }, + }), }); diff --git a/x-pack/plugins/alerting/server/routes/unmute_alert.ts b/x-pack/plugins/alerting/server/routes/unmute_alert.ts index b0d124e0d3945..ba3c639a88e52 100644 --- a/x-pack/plugins/alerting/server/routes/unmute_alert.ts +++ b/x-pack/plugins/alerting/server/routes/unmute_alert.ts @@ -13,8 +13,16 @@ import { RewriteRequestCase, verifyAccessAndContext } from './lib'; import { AlertingRequestHandlerContext, BASE_ALERTING_API_PATH } from '../types'; const paramSchema = schema.object({ - rule_id: schema.string(), - alert_id: schema.string(), + rule_id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), + alert_id: schema.string({ + meta: { + description: 'The identifier for the alert.', + }, + }), }); const rewriteParamsReq: RewriteRequestCase = ({ From 0da77e3c368f7fee92df3fc766a87b0f45db4da8 Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Wed, 17 Jul 2024 10:52:03 +0100 Subject: [PATCH 6/9] wrap params with request object in delete and mute alert api --- .../server/routes/rule/apis/delete/delete_rule_route.ts | 4 +++- .../alerting/server/routes/rule/apis/mute_alert/mute_alert.ts | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts index 3fe896cec9622..87e420492d358 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts @@ -26,7 +26,9 @@ export const deleteRuleRoute = ( summary: `Delete a rule`, }, validate: { - params: deleteRuleRequestParamsSchemaV1, + request: { + params: deleteRuleRequestParamsSchemaV1, + }, }, }, router.handleLegacyErrors( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts b/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts index 91a254be09663..3c4bc98c64d2b 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts @@ -26,7 +26,9 @@ export const muteAlertRoute = ( summary: `Mute an alert`, }, validate: { - params: muteAlertParamsSchemaV1, + request: { + params: muteAlertParamsSchemaV1, + }, }, }, router.handleLegacyErrors( From 800b75911e689208981436fb222624fd7d1e7deb Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Thu, 18 Jul 2024 14:55:02 +0100 Subject: [PATCH 7/9] use response schema v1 --- .../server/routes/rule/apis/create/create_rule_route.ts | 4 ++-- .../alerting/server/routes/rule/apis/find/find_rules_route.ts | 4 ++-- .../alerting/server/routes/rule/apis/get/get_rule_route.ts | 4 ++-- .../server/routes/rule/apis/update/update_rule_route.ts | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts index cc01599d6b2c1..84f1c6dd7c6c3 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts @@ -22,7 +22,7 @@ import { createBodySchemaV1, createParamsSchemaV1, } from '../../../../../common/routes/rule/apis/create'; -import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchemaV1 } from '../../../../../common/routes/rule/response'; import { Rule } from '../../../../application/rule/types'; import { transformCreateBodyV1 } from './transforms'; import { transformRuleToRuleResponseV1 } from '../../transforms'; @@ -43,7 +43,7 @@ export const createRuleRoute = ({ router, licenseState, usageCounter }: RouteOpt }, response: { 200: { - body: () => ruleResponseSchema, + body: () => ruleResponseSchemaV1, }, }, }, diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts index c07d9dc5e0515..117f38a068984 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts @@ -14,7 +14,7 @@ import type { FindRulesRequestQueryV1, FindRulesResponseV1, } from '../../../../../common/routes/rule/apis/find'; -import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchemaV1 } from '../../../../../common/routes/rule/response'; import { AlertingRequestHandlerContext, BASE_ALERTING_API_PATH, @@ -51,7 +51,7 @@ const buildFindRulesRoute = ({ }, response: { 200: { - body: () => ruleResponseSchema, + body: () => ruleResponseSchemaV1, }, }, }, diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts index 550a4d2c88df3..381c0f9832223 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts @@ -8,7 +8,7 @@ import { IRouter, RouteConfigOptions, RouteMethod } from '@kbn/core/server'; import { ILicenseState } from '../../../../lib'; import { verifyAccessAndContext } from '../../../lib'; -import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchemaV1 } from '../../../../../common/routes/rule/response'; import { Rule } from '../../../../application/rule/types'; import { AlertingRequestHandlerContext, @@ -47,7 +47,7 @@ const buildGetRuleRoute = ({ }, response: { 200: { - body: () => ruleResponseSchema, + body: () => ruleResponseSchemaV1, }, }, }, diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts index bd0a447302eb6..2404b5742b086 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts @@ -17,7 +17,7 @@ import { updateBodySchemaV1, updateParamsSchemaV1, } from '../../../../../common/routes/rule/apis/update'; -import { RuleParamsV1, ruleResponseSchema } from '../../../../../common/routes/rule/response'; +import { RuleParamsV1, ruleResponseSchemaV1 } from '../../../../../common/routes/rule/response'; import { AlertingRequestHandlerContext, BASE_ALERTING_API_PATH } from '../../../../types'; import { Rule } from '../../../../application/rule/types'; import { transformUpdateBodyV1 } from './transforms'; @@ -42,7 +42,7 @@ export const updateRuleRoute = ( }, response: { 200: { - body: () => ruleResponseSchema, + body: () => ruleResponseSchemaV1, }, }, }, From 6cf0ed76528f2a8dbaa8a07fb5ae7cc4763d374c Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Tue, 23 Jul 2024 10:10:16 +0100 Subject: [PATCH 8/9] update response with description --- .../common/routes/rule/response/schemas/v1.ts | 19 +++++++++++++------ .../rule/apis/create/create_rule_route.ts | 1 + .../rule/apis/delete/delete_rule_route.ts | 5 +++++ .../routes/rule/apis/find/find_rules_route.ts | 1 + .../routes/rule/apis/get/get_rule_route.ts | 1 + .../routes/rule/apis/mute_alert/mute_alert.ts | 5 +++++ .../rule/apis/update/update_rule_route.ts | 1 + 7 files changed, 27 insertions(+), 6 deletions(-) diff --git a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts index af419a4a36e21..40d83aa5efc4c 100644 --- a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts @@ -337,12 +337,19 @@ export const monitoringSchema = schema.object( }), { meta: { description: 'History of the rule run.' } } ), - calculated_metrics: schema.object({ - p50: schema.maybe(schema.number()), - p95: schema.maybe(schema.number()), - p99: schema.maybe(schema.number()), - success_ratio: schema.number(), - }), + calculated_metrics: schema.object( + { + p50: schema.maybe(schema.number()), + p95: schema.maybe(schema.number()), + p99: schema.maybe(schema.number()), + success_ratio: schema.number(), + }, + { + meta: { + description: 'Calculation of different percentiles and success ratio.', + }, + } + ), last_run: schema.object({ timestamp: schema.string({ meta: { description: 'Time when the rule was run last.' }, diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts index 84f1c6dd7c6c3..18d80fdbfec81 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts @@ -44,6 +44,7 @@ export const createRuleRoute = ({ router, licenseState, usageCounter }: RouteOpt response: { 200: { body: () => ruleResponseSchemaV1, + description: 'Indicates a successful call.', }, }, }, diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts index 87e420492d358..e64bc7a7dfff3 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/delete/delete_rule_route.ts @@ -29,6 +29,11 @@ export const deleteRuleRoute = ( request: { params: deleteRuleRequestParamsSchemaV1, }, + response: { + 204: { + description: 'Indicates a successful call.', + }, + }, }, }, router.handleLegacyErrors( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts index 117f38a068984..4eb20b5acaf05 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts @@ -52,6 +52,7 @@ const buildFindRulesRoute = ({ response: { 200: { body: () => ruleResponseSchemaV1, + description: 'Indicates a successful call.', }, }, }, diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts index 381c0f9832223..4ae47caa7a7f5 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/get/get_rule_route.ts @@ -48,6 +48,7 @@ const buildGetRuleRoute = ({ response: { 200: { body: () => ruleResponseSchemaV1, + description: 'Indicates a successful call.', }, }, }, diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts b/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts index 3c4bc98c64d2b..12babb3bf084c 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts @@ -29,6 +29,11 @@ export const muteAlertRoute = ( request: { params: muteAlertParamsSchemaV1, }, + response: { + 204: { + description: 'Indicates a successful call.', + }, + }, }, }, router.handleLegacyErrors( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts index 2404b5742b086..392bdd8991047 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts @@ -43,6 +43,7 @@ export const updateRuleRoute = ( response: { 200: { body: () => ruleResponseSchemaV1, + description: 'Indicates a successful call.', }, }, }, From b05aff0f019a84feeac1126628f363516a48406e Mon Sep 17 00:00:00 2001 From: Janki Salvi Date: Tue, 23 Jul 2024 17:32:48 +0100 Subject: [PATCH 9/9] PR feedback --- .../routes/alerts_filter_query/schemas/v1.ts | 2 +- .../routes/r_rule/response/schemas/v1.ts | 27 +++++++++---------- .../routes/rule/apis/create/schemas/v1.ts | 2 +- .../routes/rule/apis/update/schemas/v1.ts | 2 +- .../common/routes/rule/response/schemas/v1.ts | 19 ++++++------- .../routes/rule/apis/find/find_rules_route.ts | 2 +- 6 files changed, 27 insertions(+), 27 deletions(-) diff --git a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts index 324b927f40af8..2975ed7f97707 100644 --- a/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts @@ -41,7 +41,7 @@ export const alertsFilterQuerySchema = schema.object({ { meta: { description: - 'A filter is specific to an application context or whether it should be applied globally.', + 'A filter can be either specific to an application context or applied globally.', }, } ), diff --git a/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts index 5098b9b97971c..c9dec9d8cf1e6 100644 --- a/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts @@ -10,12 +10,12 @@ import { schema } from '@kbn/config-schema'; export const rRuleResponseSchema = schema.object({ dtstart: schema.string({ meta: { - description: 'Rule start date as per UTC.', + description: 'Rule start date in Coordinated Universal Time (UTC).', }, }), tzid: schema.string({ meta: { - description: 'Indicates timezone.', + description: 'Indicates timezone abbreviation.', }, }), freq: schema.maybe( @@ -55,7 +55,7 @@ export const rRuleResponseSchema = schema.object({ schema.number({ meta: { description: - 'Indicates the interval of frequency, e.g. 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.', + 'Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.', }, }) ), @@ -72,8 +72,7 @@ export const rRuleResponseSchema = schema.object({ ], { meta: { - description: - 'Indicates the start of week, defaults to Monday. The following, if not provided, will be automatically derived from the dtstart.', + description: 'Indicates the start of week, defaults to Monday.', }, } ) @@ -83,7 +82,7 @@ export const rRuleResponseSchema = schema.object({ schema.oneOf([schema.string(), schema.number()], { meta: { description: - 'Indicates day(s) of the week to recur, OR nth-day-of-month strings, e.g. "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which will get internally converted to a byweekday/bysetpos combination.', + 'Indicates the days of the week to recur or else nth-day-of-month strings. For example, "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which are internally converted to a `byweekday/bysetpos` combination.', }, }) ) @@ -92,7 +91,7 @@ export const rRuleResponseSchema = schema.object({ schema.arrayOf( schema.number({ meta: { - description: 'Indicates month(s) of the year that this rule should recur.', + description: 'Indicates months of the year that this rule should recur.', }, }) ) @@ -102,7 +101,7 @@ export const rRuleResponseSchema = schema.object({ schema.number({ meta: { description: - 'Indicates positive or negative integer affecting nth day of the month, eg -2 combined with byweekday of FR is 2nd to last Friday of the month. Best not to set this manually and just use byweekday.', + 'A positive or negative integer affecting the nth day of the month. For example, -2 combined with `byweekday` of FR is 2nd to last Friday of the month. It is recommended to not set this manually and just use `byweekday`.', }, }) ) @@ -111,7 +110,7 @@ export const rRuleResponseSchema = schema.object({ schema.arrayOf( schema.number({ meta: { - description: 'Indicates day(s) of the month to recur.', + description: 'Indicates the days of the month to recur.', }, }) ) @@ -120,7 +119,7 @@ export const rRuleResponseSchema = schema.object({ schema.arrayOf( schema.number({ meta: { - description: 'Indicates day(s) of the year that this rule should recur.', + description: 'Indicates the days of the year that this rule should recur.', }, }) ) @@ -129,7 +128,7 @@ export const rRuleResponseSchema = schema.object({ schema.arrayOf( schema.number({ meta: { - description: 'Indicates number of the week hour(s) to recur.', + description: 'Indicates number of the week hours to recur.', }, }) ) @@ -138,7 +137,7 @@ export const rRuleResponseSchema = schema.object({ schema.arrayOf( schema.number({ meta: { - description: 'Indicates hour(s) of the day to recur.', + description: 'Indicates hours of the day to recur.', }, }) ) @@ -147,7 +146,7 @@ export const rRuleResponseSchema = schema.object({ schema.arrayOf( schema.number({ meta: { - description: 'Indicates Minute(s) of the hour to recur.', + description: 'Indicates minutes of the hour to recur.', }, }) ) @@ -156,7 +155,7 @@ export const rRuleResponseSchema = schema.object({ schema.arrayOf( schema.number({ meta: { - description: 'Indicates seconds(s) of the day to recur.', + description: 'Indicates seconds of the day to recur.', }, }) ) diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts index 57e92eb284e5e..24d99239bcdf3 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts @@ -117,7 +117,7 @@ export const actionSchema = schema.object( use_alert_data_for_template: schema.maybe( schema.boolean({ meta: { - description: 'Indicates whether to use alert data as template or not.', + description: 'Indicates whether to use alert data as a template.', }, }) ), diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts index 4e3c3b28964a8..54eef7123bba1 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/update/schemas/v1.ts @@ -109,7 +109,7 @@ export const actionSchema = schema.object( use_alert_data_for_template: schema.maybe( schema.boolean({ meta: { - description: 'Indicates whether to use alert data as template or not.', + description: 'Indicates whether to use alert data as a template.', }, }) ), diff --git a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts index 40d83aa5efc4c..c513a0c53c693 100644 --- a/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts @@ -142,7 +142,7 @@ const actionSchema = schema.object({ alerts_filter: schema.maybe(actionAlertsFilterSchema), use_alert_data_for_template: schema.maybe( schema.boolean({ - meta: { description: 'Indicates whether to use alert data as template or not.' }, + meta: { description: 'Indicates whether to use alert data as a template.' }, }) ), }); @@ -312,7 +312,7 @@ export const ruleLastRunSchema = schema.object({ schema.nullable( schema.number({ meta: { - description: 'Number of ignore alerts during last run.', + description: 'Number of ignored alerts during last run.', }, }) ) @@ -327,7 +327,7 @@ export const monitoringSchema = schema.object( history: schema.arrayOf( schema.object({ success: schema.boolean({ - meta: { description: 'Indicates whether the rule run was success or not.' }, + meta: { description: 'Indicates whether the rule run was successful.' }, }), timestamp: schema.number({ meta: { description: 'Time of rule run.' } }), duration: schema.maybe( @@ -352,12 +352,12 @@ export const monitoringSchema = schema.object( ), last_run: schema.object({ timestamp: schema.string({ - meta: { description: 'Time when the rule was run last.' }, + meta: { description: 'Time of the most recent rule run.' }, }), metrics: schema.object({ duration: schema.maybe( schema.number({ - meta: { description: 'Duration of last rule run.' }, + meta: { description: 'Duration of most recent rule run.' }, }) ), total_search_duration_ms: schema.maybe( @@ -365,7 +365,7 @@ export const monitoringSchema = schema.object( schema.number({ meta: { description: - 'Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response.', + 'Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.', }, }) ) @@ -551,13 +551,14 @@ export const ruleResponseSchema = schema.object({ meta: { description: 'Deprecated in 8.13.0. Use the `throttle` property in the action `frequency` object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.', + deprecated: true, }, }) ) ), mute_all: schema.boolean({ meta: { - description: 'Indicates whether all alerts are muted or not.', + description: 'Indicates whether all alerts are muted.', }, }), notify_when: schema.maybe(schema.nullable(notifyWhenSchema)), @@ -575,7 +576,7 @@ export const ruleResponseSchema = schema.object({ schema.arrayOf( schema.string({ meta: { - description: `List of rule's active snoozes.`, + description: `List of active snoozes for the rule.`, }, }) ) @@ -584,7 +585,7 @@ export const ruleResponseSchema = schema.object({ schema.nullable( schema.string({ meta: { - description: 'Date until when rule is snoozed.', + description: 'The date when the rule will no longer be snoozed.', }, }) ) diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts index 4eb20b5acaf05..420e4b01d81e6 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts @@ -43,7 +43,7 @@ const buildFindRulesRoute = ({ path, options: { access: 'public', - summary: `Retrieves information about rules.`, + summary: `Get information about rules.`, }, validate: { request: {