[8.18] [Security Assistant] Added examples for necessary AI Assistant OpenAPI docs (#219883) (#220712)

# Backport

This will backport the following commits from `main` to `8.18`:
- [[Security Assistant] Added examples for necessary AI Assistant
OpenAPI docs (#219883)](#219883)

<!--- Backport version: 9.6.6 -->

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

<!--BACKPORT [{"author":{"name":"Steph
Milovic","email":"[email protected]"},"sourceCommit":{"committedDate":"2025-05-09T14:47:44Z","message":"[Security
Assistant] Added examples for necessary AI Assistant OpenAPI docs
(#219883)","sha":"214c5f099e61a9e0c5e893e0c417d12636e3e000","branchLabelMapping":{"^v9.1.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:
SecuritySolution","Team:Security Generative
AI","backport:version","v9.1.0","v8.19.0","v9.0.1","v8.18.2"],"title":"[Security
Assistant] Added examples for necessary AI Assistant OpenAPI
docs","number":219883,"url":"https://github.com/elastic/kibana/pull/219883","mergeCommit":{"message":"[Security
Assistant] Added examples for necessary AI Assistant OpenAPI docs
(#219883)","sha":"214c5f099e61a9e0c5e893e0c417d12636e3e000"}},"sourceBranch":"main","suggestedTargetBranches":["8.19","9.0","8.18"],"targetPullRequestStates":[{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/219883","number":219883,"mergeCommit":{"message":"[Security
Assistant] Added examples for necessary AI Assistant OpenAPI docs
(#219883)","sha":"214c5f099e61a9e0c5e893e0c417d12636e3e000"}},{"branch":"8.19","label":"v8.19.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"9.0","label":"v9.0.1","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.18","label":"v8.18.2","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

---------

Co-authored-by: kibanamachine <[email protected]>

Author: stephmilovic

oas_docs/output/kibana.yaml

@@ -16,8 +16,16 @@
 
 import { z } from '@kbn/zod';
 
-import { NonEmptyString } from '../common_attributes.gen';
-
+import {
+  BulkActionBase,
+  NonEmptyString,
+  NonEmptyTimestamp,
+  BulkCrudActionSummary,
+} from '../common_attributes.gen';
+
+/**
+ * Reason why the anonymization field was not modified.
+ */
 export type AnonymizationFieldsBulkActionSkipReason = z.infer<
   typeof AnonymizationFieldsBulkActionSkipReason
 >;
@@ -29,38 +37,92 @@ export type AnonymizationFieldsBulkActionSkipResult = z.infer<
   typeof AnonymizationFieldsBulkActionSkipResult
 >;
 export const AnonymizationFieldsBulkActionSkipResult = z.object({
+  /**
+   * The ID of the anonymization field that was not modified.
+   */
   id: z.string(),
+  /**
+   * Name of the anonymization field that was not modified.
+   */
   name: z.string().optional(),
+  /**
+   * Reason why the anonymization field was not modified.
+   */
   skip_reason: AnonymizationFieldsBulkActionSkipReason,
 });
 
 export type AnonymizationFieldDetailsInError = z.infer<typeof AnonymizationFieldDetailsInError>;
 export const AnonymizationFieldDetailsInError = z.object({
+  /**
+   * The ID of the anonymization field.
+   */
   id: z.string(),
+  /**
+   * Name of the anonymization field.
+   */
   name: z.string().optional(),
 });
 
 export type NormalizedAnonymizationFieldError = z.infer<typeof NormalizedAnonymizationFieldError>;
 export const NormalizedAnonymizationFieldError = z.object({
+  /**
+   * Error message.
+   */
   message: z.string(),
+  /**
+   * Status code of the response.
+   */
   status_code: z.number().int(),
+  /**
+   * Error code indicating the type of failure.
+   */
   err_code: z.string().optional(),
+  /**
+   * Array of anonymization fields that caused the error.
+   */
   anonymization_fields: z.array(AnonymizationFieldDetailsInError),
 });
 
 export type AnonymizationFieldResponse = z.infer<typeof AnonymizationFieldResponse>;
 export const AnonymizationFieldResponse = z.object({
+  /**
+   * The ID of the anonymization field.
+   */
   id: NonEmptyString,
-  timestamp: NonEmptyString.optional(),
+  /**
+   * Timestamp when the anonymization field was initially created.
+   */
+  timestamp: NonEmptyTimestamp.optional(),
+  /**
+   * Name of the anonymization field.
+   */
   field: z.string(),
+  /**
+   * Whether this field is allowed to be sent to the model.
+   */
   allowed: z.boolean().optional(),
+  /**
+   * Whether this field should be anonymized.
+   */
   anonymized: z.boolean().optional(),
+  /**
+   * Timestamp of the last update.
+   */
   updatedAt: z.string().optional(),
+  /**
+   * Username of the person who last updated the field.
+   */
   updatedBy: z.string().optional(),
+  /**
+   * Timestamp of when the anonymization field was created.
+   */
   createdAt: z.string().optional(),
+  /**
+   * Username of the person who created the anonymization field.
+   */
   createdBy: z.string().optional(),
   /**
-   * Kibana space
+   * Kibana space in which this anonymization field exists.
    */
   namespace: z.string().optional(),
 });
@@ -69,67 +131,98 @@ export type AnonymizationFieldsBulkCrudActionResults = z.infer<
   typeof AnonymizationFieldsBulkCrudActionResults
 >;
 export const AnonymizationFieldsBulkCrudActionResults = z.object({
+  /**
+   * List of anonymization fields successfully updated.
+   */
   updated: z.array(AnonymizationFieldResponse),
+  /**
+   * List of anonymization fields successfully created.
+   */
   created: z.array(AnonymizationFieldResponse),
   deleted: z.array(z.string()),
+  /**
+   * List of anonymization fields that were skipped during the operation.
+   */
   skipped: z.array(AnonymizationFieldsBulkActionSkipResult),
 });
 
-export type BulkCrudActionSummary = z.infer<typeof BulkCrudActionSummary>;
-export const BulkCrudActionSummary = z.object({
-  failed: z.number().int(),
-  skipped: z.number().int(),
-  succeeded: z.number().int(),
-  total: z.number().int(),
-});
-
 export type AnonymizationFieldsBulkCrudActionResponse = z.infer<
   typeof AnonymizationFieldsBulkCrudActionResponse
 >;
 export const AnonymizationFieldsBulkCrudActionResponse = z.object({
+  /**
+   * Indicates if the bulk action was successful.
+   */
   success: z.boolean().optional(),
+  /**
+   * HTTP status code returned.
+   */
   status_code: z.number().int().optional(),
+  /**
+   * Message providing information about the bulk action result.
+   */
   message: z.string().optional(),
+  /**
+   * Total number of anonymization fields processed.
+   */
   anonymization_fields_count: z.number().int().optional(),
   attributes: z.object({
     results: AnonymizationFieldsBulkCrudActionResults,
     summary: BulkCrudActionSummary,
+    /**
+     * List of errors that occurred during the bulk operation.
+     */
     errors: z.array(NormalizedAnonymizationFieldError).optional(),
   }),
 });
 
-export type BulkActionBase = z.infer<typeof BulkActionBase>;
-export const BulkActionBase = z.object({
+export type AnonymizationFieldCreateProps = z.infer<typeof AnonymizationFieldCreateProps>;
+export const AnonymizationFieldCreateProps = z.object({
   /**
-   * Query to filter anonymization fields
+   * Name of the anonymization field to create.
    */
-  query: z.string().optional(),
+  field: z.string(),
   /**
-   * Array of anonymization fields IDs
+   * Whether this field is allowed to be sent to the model.
    */
-  ids: z.array(z.string()).min(1).optional(),
-});
-
-export type AnonymizationFieldCreateProps = z.infer<typeof AnonymizationFieldCreateProps>;
-export const AnonymizationFieldCreateProps = z.object({
-  field: z.string(),
   allowed: z.boolean().optional(),
+  /**
+   * Whether this field should be anonymized.
+   */
   anonymized: z.boolean().optional(),
 });
 
 export type AnonymizationFieldUpdateProps = z.infer<typeof AnonymizationFieldUpdateProps>;
 export const AnonymizationFieldUpdateProps = z.object({
+  /**
+   * The ID of the anonymization field to update.
+   */
   id: z.string(),
+  /**
+   * Whether this field is allowed to be sent to the model.
+   */
   allowed: z.boolean().optional(),
+  /**
+   * Whether this field should be anonymized.
+   */
   anonymized: z.boolean().optional(),
 });
 
 export type PerformAnonymizationFieldsBulkActionRequestBody = z.infer<
   typeof PerformAnonymizationFieldsBulkActionRequestBody
 >;
 export const PerformAnonymizationFieldsBulkActionRequestBody = z.object({
+  /**
+   * Object containing the query to filter anonymization fields and/or an array of anonymization field IDs to delete.
+   */
   delete: BulkActionBase.optional(),
+  /**
+   * Array of anonymization fields to create.
+   */
   create: z.array(AnonymizationFieldCreateProps).optional(),
+  /**
+   * Array of anonymization fields to update.
+   */
   update: z.array(AnonymizationFieldUpdateProps).optional(),
 });
 export type PerformAnonymizationFieldsBulkActionRequestBodyInput = z.input<