[Security Assistant] Added examples for necessary AI Assistant OpenAPI docs

x-pack/platform/packages/shared/kbn-elastic-assistant-common/impl/schemas/anonymization_fields/bulk_crud_anonymization_fields_route.gen.ts

@@ -18,6 +18,9 @@ import { z } from '@kbn/zod';
 
 import { NonEmptyString } from '../common_attributes.gen';
 
+/**
+ * Reason why the anonymization field was not modified
+ */
 export type AnonymizationFieldsBulkActionSkipReason = z.infer<
   typeof AnonymizationFieldsBulkActionSkipReason
 >;
@@ -29,35 +32,89 @@ export type AnonymizationFieldsBulkActionSkipResult = z.infer<
   typeof AnonymizationFieldsBulkActionSkipResult
 >;
 export const AnonymizationFieldsBulkActionSkipResult = z.object({
+  /**
+   * 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({
+  /**
+   * 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
+   */
   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({
+  /**
+   * id of the anonymization field
+   */
   id: NonEmptyString,
+  /**
+   * Timestamp of the field creation
+   */
   timestamp: NonEmptyString.optional(),
+  /**
+   * Field name
+   */
   field: z.string(),
+  /**
+   * Whether field is allowed to be sent to the model
+   */
   allowed: z.boolean().optional(),
+  /**
+   * Whether field is anonymized
+   */
   anonymized: z.boolean().optional(),
+  /**
+   * Timestamp of the last update
+   */
   updatedAt: z.string().optional(),
+  /**
+   * User who last updated the field
+   */
   updatedBy: z.string().optional(),
+  /**
+   * Timestamp of the creation
+   */
   createdAt: z.string().optional(),
+  /**
+   * User who created the field
+   */
   createdBy: z.string().optional(),
   /**
    * Kibana space
@@ -100,13 +157,7 @@ export const AnonymizationFieldsBulkCrudActionResponse = z.object({
 
 export type BulkActionBase = z.infer<typeof BulkActionBase>;
 export const BulkActionBase = z.object({
-  /**
-   * Query to filter anonymization fields
-   */
   query: z.string().optional(),
-  /**
-   * Array of anonymization fields IDs
-   */
   ids: z.array(z.string()).min(1).optional(),
 });
 
@@ -128,8 +179,17 @@ export type PerformAnonymizationFieldsBulkActionRequestBody = z.infer<
   typeof PerformAnonymizationFieldsBulkActionRequestBody
 >;
 export const PerformAnonymizationFieldsBulkActionRequestBody = z.object({
+  /**
+   * Object with query to filter anonymization fields and array of anonymization fields IDs
+   */
   delete: BulkActionBase.optional(),
+  /**
+   * Array of objects with anonymization fields to create
+   */
   create: z.array(AnonymizationFieldCreateProps).optional(),
+  /**
+   * Array of objects with anonymization fields to update
+   */
   update: z.array(AnonymizationFieldUpdateProps).optional(),
 });
 export type PerformAnonymizationFieldsBulkActionRequestBodyInput = z.input<

x-pack/platform/packages/shared/kbn-elastic-assistant-common/impl/schemas/anonymization_fields/bulk_crud_anonymization_fields_route.schema.yaml

@@ -20,21 +20,84 @@ paths:
               properties:
                 delete:
                   $ref: '#/components/schemas/BulkActionBase'
+                  description: Object with query to filter anonymization fields and array of anonymization fields IDs
                 create:
                   type: array
                   items:
                     $ref: '#/components/schemas/AnonymizationFieldCreateProps'
+                  description: Array of objects with anonymization fields to create
                 update:
                   type: array
                   items:
                     $ref: '#/components/schemas/AnonymizationFieldUpdateProps'
+                  description: Array of objects with anonymization fields to update
+            example:
+              delete:
+                query: 'field: field1'
+                ids:
+                  - 'field5'
+                  - 'field6'
+              create:
+                - field: field1
+                  allowed: true
+                  anonymized: false
+                - field: field2
+                  allowed: false
+                  anonymized: true
+              update:
+                - id: field8
+                  allowed: true
+                  anonymized: false
+                - id: field9
+                  allowed: false
+                  anonymized: true
       responses:
         200:
           description: Indicates a successful call.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AnonymizationFieldsBulkCrudActionResponse'
+              example:
+                success: true
+                status_code: 200
+                message: Bulk action completed successfully
+                anonymization_fields_count: 5
+                attributes:
+                  results:
+                    updated:
+                      - id: field8
+                        field: field8
+                        allowed: true
+                        anonymized: false
+                        timestamp: '2023-10-31T12:00:00Z'
+                        updatedAt: '2023-10-31T12:00:00Z'
+                        updatedBy: user1
+                        createdAt: '2023-10-31T12:00:00Z'
+                        createdBy: user1
+                        namespace: default
+                    created:
+                      - id: field2
+                        field: field2
+                        allowed: false
+                        anonymized: true
+                        timestamp: '2023-10-31T12:00:00Z'
+                        updatedAt: '2023-10-31T12:00:00Z'
+                        updatedBy: user1
+                        createdAt: '2023-10-31T12:00:00Z'
+                        createdBy: user1
+                        namespace: default
+                    deleted:
+                      - field3
+                    skipped:
+                      - id: field4
+                        name: field4
+                        skip_reason: ANONYMIZATION_FIELD_NOT_MODIFIED
+                  summary:
+                    failed: 1
+                    skipped: 1
+                    succeeded: 2
+                    total: 5
         400:
           description: Generic Error
           content:
@@ -44,15 +107,23 @@ paths:
                 properties:
                   statusCode:
                     type: number
+                    description: status code of the response
                   error:
                     type: string
+                    description: error message
                   message:
                     type: string
+                    description: detailed error message
+              example:
+                statusCode: 400
+                error: Bad Request
+                message: Invalid request body
 
 components:
   schemas:
     AnonymizationFieldsBulkActionSkipReason:
       type: string
+      description: Reason why the anonymization field was not modified
       enum:
         - ANONYMIZATION_FIELD_NOT_MODIFIED
 
@@ -61,10 +132,13 @@ components:
       properties:
         id:
           type: string
+          description: id of the anonymization field that was not modified
         name:
           type: string
+          description: name of the anonymization field that was not modified
         skip_reason:
           $ref: '#/components/schemas/AnonymizationFieldsBulkActionSkipReason'
+          description: reason why the anonymization field was not modified
       required:
         - id
         - skip_reason
@@ -74,8 +148,10 @@ components:
       properties:
         id:
           type: string
+          description: id of the anonymization field
         name:
           type: string
+          description: name of the anonymization field
       required:
         - id
 
@@ -84,14 +160,18 @@ components:
       properties:
         message:
           type: string
+          description: error message
         status_code:
           type: integer
+          description: status code of the response
         err_code:
           type: string
+          description: error code
         anonymization_fields:
           type: array
           items:
             $ref: '#/components/schemas/AnonymizationFieldDetailsInError'
+          description: array of anonymization fields that caused the error
       required:
         - message
         - status_code
@@ -105,22 +185,31 @@ components:
       properties:
         id:
           $ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
-        'timestamp':
+          description: id of the anonymization field
+        timestamp:
           $ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
+          description: Timestamp of the field creation
         field:
           type: string
+          description: Field name
         allowed:
           type: boolean
+          description: Whether field is allowed to be sent to the model
         anonymized:
           type: boolean
+          description: Whether field is anonymized
         updatedAt:
           type: string
+          description: Timestamp of the last update
         updatedBy:
           type: string
+          description: User who last updated the field
         createdAt:
           type: string
+          description: Timestamp of the creation
         createdBy:
           type: string
+          description: User who created the field
         namespace:
           type: string
           description: Kibana space
@@ -140,6 +229,7 @@ components:
           type: array
           items:
             type: string
+            description: array of deleted anonymization field IDs
         skipped:
           type: array
           items:
@@ -155,12 +245,16 @@ components:
       properties:
         failed:
           type: integer
+          example: 1
         skipped:
           type: integer
+          example: 2
         succeeded:
           type: integer
+          example: 3
         total:
           type: integer
+          example: 6
       required:
         - failed
         - skipped
@@ -201,10 +295,8 @@ components:
       properties:
         query:
           type: string
-          description: Query to filter anonymization fields
         ids:
           type: array
-          description: Array of anonymization fields IDs
           minItems: 1
           items:
             type: string

x-pack/platform/packages/shared/kbn-elastic-assistant-common/impl/schemas/anonymization_fields/find_anonymization_fields_route.gen.ts

@@ -35,6 +35,9 @@ export type FindAnonymizationFieldsRequestQuery = z.infer<
   typeof FindAnonymizationFieldsRequestQuery
 >;
 export const FindAnonymizationFieldsRequestQuery = z.object({
+  /**
+   * Fields to return
+   */
   fields: ArrayFromString(z.string()).optional(),
   /**
    * Search query