From 2f05849f65e87281df89456cd30281b45ac44a1e Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Mon, 18 Nov 2024 02:12:06 -0800
Subject: [PATCH] [8.16] [OpenAPI][DOCS] Add descriptions for alerting rule
 flapping properties (#200112) (#200221)

# Backport

This will backport the following commits from `main` to `8.16`:
- [[OpenAPI][DOCS] Add descriptions for alerting rule flapping
properties (#200112)](https://github.com/elastic/kibana/pull/200112)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2024-11-14T15:54:51Z","message":"[OpenAPI][DOCS]
Add descriptions for alerting rule flapping properties
(#200112)","sha":"50f0016cd7b01eabc280aca4131f843ff305231d","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:Alerting","release_note:skip","Team:ResponseOps","v9.0.0","backport:version","v8.17.0","v8.16.1"],"number":200112,"url":"https://github.com/elastic/kibana/pull/200112","mergeCommit":{"message":"[OpenAPI][DOCS]
Add descriptions for alerting rule flapping properties
(#200112)","sha":"50f0016cd7b01eabc280aca4131f843ff305231d"}},"sourceBranch":"main","suggestedTargetBranches":["8.x","8.16"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/200112","number":200112,"mergeCommit":{"message":"[OpenAPI][DOCS]
Add descriptions for alerting rule flapping properties
(#200112)","sha":"50f0016cd7b01eabc280aca4131f843ff305231d"}},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.1","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->
---
 oas_docs/bundle.json                          | 18 ++++++
 oas_docs/output/kibana.yaml                   | 60 +++++++++++++++++++
 .../routes/rule/common/flapping/schemas/v1.ts | 13 +++-
 3 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/oas_docs/bundle.json b/oas_docs/bundle.json
index a0469257cacd..256c2f000554 100644
--- a/oas_docs/bundle.json
+++ b/oas_docs/bundle.json
@@ -1853,14 +1853,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -2690,14 +2693,17 @@
                   },
                   "flapping": {
                     "additionalProperties": false,
+                    "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                     "nullable": true,
                     "properties": {
                       "look_back_window": {
+                        "description": "The minimum number of runs in which the threshold must be met.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
                       },
                       "status_change_threshold": {
+                        "description": "The minimum number of times an alert must switch states in the look back window.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
@@ -3091,14 +3097,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -3918,14 +3927,17 @@
                   },
                   "flapping": {
                     "additionalProperties": false,
+                    "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                     "nullable": true,
                     "properties": {
                       "look_back_window": {
+                        "description": "The minimum number of runs in which the threshold must be met.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
                       },
                       "status_change_threshold": {
+                        "description": "The minimum number of times an alert must switch states in the look back window.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
@@ -4312,14 +4324,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -5817,14 +5832,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
index be8a00b795e3..6cffba350bcf 100644
--- a/oas_docs/output/kibana.yaml
+++ b/oas_docs/output/kibana.yaml
@@ -1652,14 +1652,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -2425,14 +2435,24 @@ paths:
                   type: boolean
                 flapping:
                   additionalProperties: false
+                  description: >-
+                    When flapping detection is turned on, alerts that switch
+                    quickly between active and recovered states are identified
+                    as “flapping” and notifications are reduced.
                   nullable: true
                   type: object
                   properties:
                     look_back_window:
+                      description: >-
+                        The minimum number of runs in which the threshold must
+                        be met.
                       maximum: 20
                       minimum: 2
                       type: number
                     status_change_threshold:
+                      description: >-
+                        The minimum number of times an alert must switch states
+                        in the look back window.
                       maximum: 20
                       minimum: 2
                       type: number
@@ -2825,14 +2845,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -3577,14 +3607,24 @@ paths:
                     - active
                 flapping:
                   additionalProperties: false
+                  description: >-
+                    When flapping detection is turned on, alerts that switch
+                    quickly between active and recovered states are identified
+                    as “flapping” and notifications are reduced.
                   nullable: true
                   type: object
                   properties:
                     look_back_window:
+                      description: >-
+                        The minimum number of runs in which the threshold must
+                        be met.
                       maximum: 20
                       minimum: 2
                       type: number
                     status_change_threshold:
+                      description: >-
+                        The minimum number of times an alert must switch states
+                        in the look back window.
                       maximum: 20
                       minimum: 2
                       type: number
@@ -3969,14 +4009,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -5205,14 +5255,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
diff --git a/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts
index 4844a9e808ef..acdd35854df3 100644
--- a/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts
+++ b/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts
@@ -17,13 +17,24 @@ import { validateFlapping as validateFlappingV1 } from '../../../validation/vali
 export const flappingSchema = schema.object(
   {
     look_back_window: schema.number({
+      meta: { description: 'The minimum number of runs in which the threshold must be met.' },
       min: MIN_LOOK_BACK_WINDOW_V1,
       max: MAX_LOOK_BACK_WINDOW_V1,
     }),
     status_change_threshold: schema.number({
+      meta: {
+        description:
+          'The minimum number of times an alert must switch states in the look back window.',
+      },
       min: MIN_STATUS_CHANGE_THRESHOLD_V1,
       max: MAX_STATUS_CHANGE_THRESHOLD_V1,
     }),
   },
-  { validate: validateFlappingV1 }
+  {
+    validate: validateFlappingV1,
+    meta: {
+      description:
+        'When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.',
+    },
+  }
 );