[8.18] [Detection Engine][Docs] Updating examples to meet old ascii docs (#207558) (#209942)

# Backport

This will backport the following commits from `main` to `8.18`:
- [[Detection Engine][Docs] Updating examples to meet old ascii docs
(#207558)](#207558)

<!--- Backport version: 9.6.4 -->

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

<!--BACKPORT [{"author":{"name":"Yara
Tercero","email":"[email protected]"},"sourceCommit":{"committedDate":"2025-02-05T07:02:48Z","message":"[Detection
Engine][Docs] Updating examples to meet old ascii docs (#207558)\n\n#
Summary\r\n\r\nAs part of the effort to add missing content for Security
APIs, this PR\r\nintroduces a few missing request, response, and
parameter examples for\r\nDetection Engine Alert and migration
APIs.","sha":"d4199dcac1f0bff5f3511e79a860c77534b35c74","branchLabelMapping":{"^v9.1.0$":"main","^v8.19.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","Team:Detection
Engine","v8.16.0","backport:version","v8.17.0","v8.18.0","v9.1.0"],"title":"[Detection
Engine][Docs] Updating examples to meet old ascii
docs","number":207558,"url":"https://github.com/elastic/kibana/pull/207558","mergeCommit":{"message":"[Detection
Engine][Docs] Updating examples to meet old ascii docs (#207558)\n\n#
Summary\r\n\r\nAs part of the effort to add missing content for Security
APIs, this PR\r\nintroduces a few missing request, response, and
parameter examples for\r\nDetection Engine Alert and migration
APIs.","sha":"d4199dcac1f0bff5f3511e79a860c77534b35c74"}},"sourceBranch":"main","suggestedTargetBranches":["9.0","8.16","8.17","8.18"],"targetPullRequestStates":[{"branch":"9.0","label":"v9.0.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.17","label":"v8.17.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.18","label":"v8.18.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/207558","number":207558,"mergeCommit":{"message":"[Detection
Engine][Docs] Updating examples to meet old ascii docs (#207558)\n\n#
Summary\r\n\r\nAs part of the effort to add missing content for Security
APIs, this PR\r\nintroduces a few missing request, response, and
parameter examples for\r\nDetection Engine Alert and migration
APIs.","sha":"d4199dcac1f0bff5f3511e79a860c77534b35c74"}}]}] BACKPORT-->

Author: yctercero

oas_docs/output/kibana.serverless.yaml

@@ -15,20 +15,14 @@
  */
 
 import { z } from '@kbn/zod';
+import { isNonEmptyString } from '@kbn/zod-helpers';
 
 import { AlertIds } from '../../model/alert.gen';
-import { NonEmptyString } from '../../model/primitives.gen';
 
 export type AlertAssignees = z.infer<typeof AlertAssignees>;
 export const AlertAssignees = z.object({
-  /**
-   * A list of users ids to assign.
-   */
-  add: z.array(NonEmptyString),
-  /**
-   * A list of users ids to unassign.
-   */
-  remove: z.array(NonEmptyString),
+  add: z.array(z.string().min(1).superRefine(isNonEmptyString)),
+  remove: z.array(z.string().min(1).superRefine(isNonEmptyString)),
 });
 
 export type SetAlertAssigneesRequestBody = z.infer<typeof SetAlertAssigneesRequestBody>;
@@ -37,9 +31,6 @@ export const SetAlertAssigneesRequestBody = z.object({
    * Details about the assignees to assign and unassign.
    */
   assignees: AlertAssignees,
-  /**
-   * List of alerts ids to assign and unassign passed assignees.
-   */
   ids: AlertIds,
 });
 export type SetAlertAssigneesRequestBodyInput = z.input<typeof SetAlertAssigneesRequestBody>;

oas_docs/output/kibana.yaml

@@ -28,10 +28,42 @@ paths:
                   description: Details about the assignees to assign and unassign.
                 ids:
                   $ref: '../../model/alert.schema.yaml#/components/schemas/AlertIds'
-                  description: List of alerts ids to assign and unassign passed assignees.
+            examples:
+              add:
+                value:
+                  assignees:
+                    add: ['u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0']
+                    remove: []
+                  ids: ['681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6']
+              remove:
+                value:
+                  assignees:
+                    add: []
+                    remove: ['u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0']
+                  ids: ['681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6']
       responses:
         200:
           description: Indicates a successful call.
+          content:
+            application/ndjson:
+              examples:
+                add:
+                  value:
+                    took: 76,
+                    timed_out: false,
+                    total: 1,
+                    updated: 1,
+                    deleted: 0,
+                    batches: 1,
+                    version_conflicts: 0,
+                    noops: 0,
+                    retries:
+                      - bulk: 0,
+                      - search: 0
+                    throttled_millis: 0,
+                    requests_per_second: -1,
+                    throttled_until_millis: 0,
+                    failures: []
         400:
           description: Invalid request.
 
@@ -46,10 +78,14 @@ components:
         add:
           type: array
           items:
-            $ref: '../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
-          description: A list of users ids to assign.
+            type: string
+            format: nonempty
+            minLength: 1
+            description: A list of users ids to assign.
         remove:
           type: array
           items:
-            $ref: '../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
-          description: A list of users ids to unassign.
+            type: string
+            format: nonempty
+            minLength: 1
+            description: A list of users ids to unassign.

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.gen.ts

@@ -18,6 +18,9 @@ import { z } from '@kbn/zod';
 
 import { AlertIds, AlertTags } from '../../../model/alert.gen';
 
+/**
+ * Object with list of tags to add and remove.
+ */
 export type SetAlertTags = z.infer<typeof SetAlertTags>;
 export const SetAlertTags = z.object({
   tags_to_add: AlertTags,

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml

@@ -30,6 +30,19 @@ paths:
               required:
                 - ids
                 - tags
+            examples:
+              add:
+                value:
+                  tags:
+                    tags_to_add: ['Duplicate']
+                    tags_to_remove: []
+                  ids: ['549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e']
+              remove:
+                value:
+                  tags:
+                    tags_to_add: []
+                    tags_to_remove: ['Duplicate']
+                  ids: ['549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e']
       responses:
         200:
           description: Successful response
@@ -39,6 +52,24 @@ paths:
                 type: object
                 additionalProperties: true
                 description: Elasticsearch update by query response
+              examples:
+                success:
+                  value:
+                    took: 68,
+                    timed_out: false,
+                    total: 1,
+                    updated: 1,
+                    deleted: 0,
+                    batches: 1,
+                    version_conflicts: 0,
+                    noops: 0,
+                    retries:
+                      bulk: 0,
+                      search: 0
+                    throttled_millis: 0,
+                    requests_per_second: -1,
+                    throttled_until_millis: 0,
+                    failures: []
         400:
           description: Invalid input data response
           content:
@@ -63,6 +94,7 @@ paths:
 components:
   schemas:
     SetAlertTags:
+      description: Object with list of tags to add and remove.
       type: object
       properties:
         tags_to_add:

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.gen.ts

@@ -25,6 +25,11 @@ paths:
                     type: boolean
                     nullable: true
                 required: [name, index_mapping_outdated]
+              examples:
+                success:
+                  value:
+                    index_mapping_outdated: false
+                    name: '.alerts-security.alerts-default'
         401:
           description: Unsuccessful authentication response
           content:

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml

@@ -29,6 +29,42 @@ paths:
                   has_encryption_key:
                     type: boolean
                 required: [is_authenticated, has_encryption_key]
+              examples:
+                success:
+                  value:
+                    username: elastic
+                    has_all_requested: true
+                    cluster:
+                      all: true
+                      monitor_ml: true
+                      manage_transform: true
+                      manage_index_templates: true
+                      monitor_transform: true
+                      manage_ml: true
+                      monitor: true
+                      manage_pipeline: true
+                      manage_api_key: true
+                      manage_security: true
+                      manage_own_api_key: true
+                      manage: true
+                    index:
+                      .alerts-security.alerts-default:
+                        all: true
+                        create: true
+                        create_doc: true
+                        create_index: true
+                        delete: true
+                        delete_index: true
+                        index: true
+                        maintenance: true
+                        manage: true
+                        monitor: true
+                        read: true
+                        view_index_metadata: true
+                        write: true
+                    application: {}
+                    is_authenticated: true
+                    has_encryption_key: true
         401:
           description: Unsuccessful authentication response
           content:

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_index/read_index.schema.yaml

@@ -48,6 +48,35 @@ paths:
                 sort:
                   $ref: '#/components/schemas/AlertsSort'
               description: Elasticsearch query and aggregation request
+            examples:
+              query:
+                value:
+                  size: 0
+                  query:
+                    bool:
+                      filter:
+                        - bool:
+                            must: []
+                            filter:
+                              - match_phrase:
+                                  kibana.alert.workflow_status: open
+                            should: []
+                            must_not:
+                              - exists:
+                                  field: kibana.alert.building_block_type
+                        - range:
+                            '@timestamp':
+                              gte: 2025-01-17T08:00:00.000Z
+                              lte: 2025-01-18T07:59:59.999Z
+                  aggs:
+                    alertsByGrouping:
+                      terms:
+                        field: host.name
+                        size: 10
+                    missingFields:
+                      missing:
+                        field: host.name
+                  runtime_mappings: {}
       responses:
         200:
           description: Successful response
@@ -57,6 +86,31 @@ paths:
                 type: object
                 additionalProperties: true
                 description: Elasticsearch search response
+              examples:
+                success:
+                  value:
+                    took: 0
+                    timed_out: false
+                    _shards:
+                      total: 1
+                      successful: 1
+                      skipped: 0
+                      failed: 0
+                    hits:
+                      total:
+                        value: 5
+                        relation: eq
+                      max_score: null
+                      hits: []
+                    aggregations:
+                      alertsByGrouping:
+                        doc_count_error_upper_bound: 0
+                        sum_other_doc_count: 0
+                        buckets:
+                          - key: Host-f43kkddfyc
+                            doc_count: 5
+                      missingFields:
+                        doc_count: 0
         400:
           description: Invalid input data response
           content:

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_privileges/read_privileges.schema.yaml

@@ -15,13 +15,16 @@
  */
 
 import { z } from '@kbn/zod';
+import { isNonEmptyString } from '@kbn/zod-helpers';
 
-import { NonEmptyString } from '../../../model/primitives.gen';
 import { AlertStatus } from '../../../model/alert.gen';
 
 export type SetAlertsStatusByIds = z.infer<typeof SetAlertsStatusByIds>;
 export const SetAlertsStatusByIds = z.object({
-  signal_ids: z.array(NonEmptyString).min(1),
+  /**
+   * List of alert `id`s.
+   */
+  signal_ids: z.array(z.string().min(1).superRefine(isNonEmptyString)).min(1),
   status: AlertStatus,
 });