[ResponseOps][Rules] OAS schema registration for Rule APIs

x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts

@@ -9,20 +9,57 @@ 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())),
-      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([
-            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.',
+              },
+            }
+          ),
         })
       ),
+    }),
+    {
+      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({
+      meta: {
+        description: 'A filter written in Elasticsearch Query Domain Specific Language (DSL).',
+      },
     })
   ),
-  dsl: schema.maybe(schema.string()),
 });

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

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.' },
@@ -183,5 +189,11 @@ export const createBodySchema = schema.object({
 });
 
 export const createParamsSchema = schema.object({
-  id: schema.maybe(schema.string()),
+  id: schema.maybe(
+    schema.string({
+      meta: {
+        description: 'The identifier for the rule.',
+      },
+    })
+  ),
 });

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