[8.9] [OAS] Clarify rule action descriptions (#162199) (#163418)

# Backport

This will backport the following commits from `main` to `8.9`:
- [[OAS] Clarify rule action descriptions
(#162199)](https://github.com/elastic/kibana/pull/162199)

<!--- Backport version: 8.9.7 -->

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

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2023-08-08T14:31:46Z","message":"[OAS]
Clarify rule action descriptions
(#162199)","sha":"bc9d601febb56c19a677dbed3312a2012bdedc97","branchLabelMapping":{"^v8.10.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:Alerting","release_note:skip","Team:ResponseOps","backport:prev-minor","v8.10.0"],"number":162199,"url":"https://github.com/elastic/kibana/pull/162199","mergeCommit":{"message":"[OAS]
Clarify rule action descriptions
(#162199)","sha":"bc9d601febb56c19a677dbed3312a2012bdedc97"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.10.0","labelRegex":"^v8.10.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/162199","number":162199,"mergeCommit":{"message":"[OAS]
Clarify rule action descriptions
(#162199)","sha":"bc9d601febb56c19a677dbed3312a2012bdedc97"}}]}]
BACKPORT-->

Co-authored-by: Lisa Cawley <lcawley@elastic.co>

docs/api-generated/rules/rule-apis-passthru.asciidoc

@@ -3113,14 +3113,14 @@ Any modifications made to this file will be overwritten.
   </div>
   <div class="model">
     <h3><a name="actions_inner"><code>actions_inner</code> - </a> <a class="up" href="#__Models">Up</a></h3>
-    <div class='model-description'></div>
+    <div class='model-description'>An action that runs under defined conditions.</div>
     <div class="field-items">
       <div class="param">alerts_filter (optional)</div><div class="param-desc"><span class="param-type"><a href="#actions_inner_alerts_filter">actions_inner_alerts_filter</a></span>  </div>
 <div class="param">connector_type_id (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The type of connector. This property appears in responses but cannot be set in requests. </div>
 <div class="param">frequency (optional)</div><div class="param-desc"><span class="param-type"><a href="#actions_inner_frequency">actions_inner_frequency</a></span>  </div>
-<div class="param">group (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The group name for the actions. If you don't need to group actions, set to <code>default</code>. </div>
-<div class="param">id (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The identifier for the connector saved object. </div>
-<div class="param">params (optional)</div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> The parameters for the action, which are sent to the connector. The <code>params</code> are handled as Mustache templates and passed a default set of context. </div>
+<div class="param">group </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> 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 <code>default</code>. </div>
+<div class="param">id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The identifier for the connector saved object. </div>
+<div class="param">params </div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> The parameters for the action, which are sent to the connector. The <code>params</code> are handled as Mustache templates and passed a default set of context. </div>
 <div class="param">uuid (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> A universally unique identifier (UUID) for the action. </div>
     </div>  <!-- field-items -->
   </div>
@@ -3159,7 +3159,7 @@ Any modifications made to this file will be overwritten.
   </div>
   <div class="model">
     <h3><a name="actions_inner_frequency"><code>actions_inner_frequency</code> - </a> <a class="up" href="#__Models">Up</a></h3>
-    <div class='model-description'>The parameters that affect how often actions are generated. NOTE: You cannot specify these parameters when <code>notify_when</code> or <code>throttle</code> are defined at the rule level.</div>
+    <div class='model-description'>The properties that affect how often actions are generated. If the rule type supports setting <code>summary</code> to <code>true</code>, the action can be a summary of alerts at the specified notification interval. Otherwise, an action runs for each alert at the specified notification interval. NOTE: You cannot specify these parameters when <code>notify_when</code> or <code>throttle</code> are defined at the rule level.</div>
     <div class="field-items">
       <div class="param">notify_when </div><div class="param-desc"><span class="param-type"><a href="#notify_when">notify_when</a></span>  </div>
 <div class="param">summary </div><div class="param-desc"><span class="param-type"><a href="#boolean">Boolean</a></span> Indicates whether the action is a summary. </div>

x-pack/plugins/alerting/docs/openapi/bundled.json

@@ -2616,14 +2616,15 @@
       "actions": {
         "type": "array",
         "default": [],
-        "required": [
-          "group",
-          "id",
-          "params"
-        ],
         "nullable": true,
         "items": {
           "type": "object",
+          "required": [
+            "group",
+            "id",
+            "params"
+          ],
+          "description": "An action that runs under defined conditions.\n",
           "properties": {
             "alerts_filter": {
               "type": "object",
@@ -2696,7 +2697,7 @@
             },
             "frequency": {
               "type": "object",
-              "description": "The parameters that affect how often actions are generated. NOTE: You cannot specify these parameters when `notify_when` or `throttle` are defined at the rule level.\n",
+              "description": "The properties that affect how often actions are generated. If the rule type supports setting `summary` to `true`, the action can be a summary of alerts at the specified notification interval. Otherwise, an action runs for each alert at the specified notification interval. NOTE: You cannot specify these parameters when `notify_when` or `throttle` are defined at the rule level.\n",
               "required": [
                 "notify_when",
                 "summary"
@@ -2716,7 +2717,7 @@
             },
             "group": {
               "type": "string",
-              "description": "The group name for the actions. If you don't need to group actions, set to `default`.",
+              "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`.\n",
               "example": "default"
             },
             "id": {

x-pack/plugins/alerting/docs/openapi/bundled.yaml

@@ -1656,13 +1656,15 @@ components:
     actions:
       type: array
       default: []
-      required:
-        - group
-        - id
-        - params
       nullable: true
       items:
         type: object
+        required:
+          - group
+          - id
+          - params
+        description: |
+          An action that runs under defined conditions.
         properties:
           alerts_filter:
             type: object
@@ -1721,7 +1723,7 @@ components:
           frequency:
             type: object
             description: |
-              The parameters that affect how often actions are generated. NOTE: You cannot specify these parameters when `notify_when` or `throttle` are defined at the rule level.
+              The properties that affect how often actions are generated. If the rule type supports setting `summary` to `true`, the action can be a summary of alerts at the specified notification interval. Otherwise, an action runs for each alert at the specified notification interval. NOTE: You cannot specify these parameters when `notify_when` or `throttle` are defined at the rule level.
             required:
               - notify_when
               - summary
@@ -1735,7 +1737,8 @@ components:
                 $ref: '#/components/schemas/throttle'
           group:
             type: string
-            description: The group name for the actions. If you don't need to group actions, set to `default`.
+            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`.
             example: default
           id:
             type: string

x-pack/plugins/alerting/docs/openapi/components/schemas/actions.yaml

@@ -1,12 +1,14 @@
 type: array
 default: []
-required:
-  - group
-  - id
-  - params
 nullable: true
 items:
   type: object
+  required:
+  - group
+  - id
+  - params
+  description: >
+    An action that runs under defined conditions.
   properties:
     alerts_filter:
       type: object
@@ -64,7 +66,9 @@ items:
     frequency:
       type: object
       description: >
-        The parameters that affect how often actions are generated.
+        The properties that affect how often actions are generated.
+        If the rule type supports setting `summary` to `true`, the action can be a summary of alerts at the specified notification interval.
+        Otherwise, an action runs for each alert at the specified notification interval.
         NOTE: You cannot specify these parameters when `notify_when` or `throttle` are defined at the rule level.
       required:
         - notify_when
@@ -79,7 +83,10 @@ items:
           $ref: 'throttle.yaml'
     group:
       type: string
-      description: The group name for the actions. If you don't need to group actions, set to `default`.
+      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`.
       example: default
     id:
       type: string