[ResponseOps][Rules] OAS schema registration for Rule APIs (#188445)

## Summary Issue: #187574 This PR updates `request` and `response` schemas below for rule APIs to generate OAS documentation: - `POST /api/alerting/rule/{id?}` - `GET /api/alerting/rule/{id}` - `DELETE /api/alerting/rule/{id}` - `PUT /api/alerting/rule/{id}` - `GET /api/alerting/rules/_find` - `POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute` ### How to test 1. Start ES 2. Add `server.oas.enabled: true` to `kibana.dev.yml` 3. Start Kibana `yarn start --no-base-path` 4. `curl -s -uelastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/alerting/rule/ | jq` 5. For find api run `curl -s -uelastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/alerting/rules/ | jq`
elastic · Jul 24, 2024 · 9422ef9 · 9422ef9
1 parent c77cd80
commit 9422ef9
Show file tree

Hide file tree

Showing 16 changed files with 1,042 additions and 250 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
@@ -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 can be either specific to an application context or 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()),
 });
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
@@ -8,40 +8,156 @@
 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 in Coordinated Universal Time (UTC).',
+    },
+  }),
+  tzid: schema.string({
+    meta: {
+      description: 'Indicates timezone abbreviation.',
+    },
+  }),
   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. For example, 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.',
+        },
+      }
+    )
+  ),
+  byweekday: schema.maybe(
+    schema.arrayOf(
+      schema.oneOf([schema.string(), schema.number()], {
+        meta: {
+          description:
+            '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.',
+        },
+      })
+    )
+  ),
+  bymonth: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description: 'Indicates months of the year that this rule should recur.',
+        },
+      })
+    )
+  ),
+  bysetpos: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description:
+            '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`.',
+        },
+      })
+    )
+  ),
+  bymonthday: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description: 'Indicates the days of the month to recur.',
+        },
+      })
+    )
+  ),
+  byyearday: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description: 'Indicates the days of the year that this rule should recur.',
+        },
+      })
+    )
+  ),
+  byweekno: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description: 'Indicates number of the week hours to recur.',
+        },
+      })
+    )
+  ),
+  byhour: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description: 'Indicates hours of the day to recur.',
+        },
+      })
+    )
+  ),
+  byminute: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description: 'Indicates minutes of the hour to recur.',
+        },
+      })
+    )
+  ),
+  bysecond: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          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
@@ -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 a template.',
+        },
+      })
+    ),
   },
   {
     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.',
+      },
+    })
+  ),
 });
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
@@ -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.',
+    },
+  }),
 });