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

Author: stephmilovic

oas_docs/output/kibana.serverless.yaml

@@ -54,7 +54,7 @@ export const ExecuteConnectorRequestBody = z.object({
   langSmithApiKey: z.string().optional(),
   screenContext: ScreenContext.optional(),
   /**
-   * optional system prompt, will be appended to default system prompt. Different from conversation system prompt, which is retrieved on the server
+   * System prompt, will be appended to default system prompt. Different from conversation system prompt, which is retrieved on the server
    */
   promptIds: PromptIds.optional(),
 });

oas_docs/output/kibana.yaml

@@ -73,7 +73,7 @@ paths:
                   $ref: '../common_attributes.schema.yaml#/components/schemas/ScreenContext'
                 promptIds:
                   $ref: '../common_attributes.schema.yaml#/components/schemas/PromptIds'
-                  description: optional system prompt, will be appended to default system prompt. Different from conversation system prompt, which is retrieved on the server
+                  description: System prompt, will be appended to default system prompt. Different from conversation system prompt, which is retrieved on the server
       responses:
         '200':
           description: Successful static response

x-pack/platform/packages/shared/kbn-elastic-assistant-common/docs/openapi/ess/elastic_assistant_api_2023_10_31.bundled.schema.yaml

@@ -16,7 +16,13 @@
 
 import { z } from '@kbn/zod';
 
-import { NonEmptyString, User } from '../common_attributes.gen';
+import {
+  BulkActionBase,
+  NonEmptyString,
+  NonEmptyTimestamp,
+  User,
+  BulkCrudActionSummary,
+} from '../common_attributes.gen';
 import { Replacements } from '../conversations/common_attributes.gen';
 
 export type AlertSummaryBulkActionSkipReason = z.infer<typeof AlertSummaryBulkActionSkipReason>;
@@ -47,7 +53,7 @@ export type AlertSummaryResponse = z.infer<typeof AlertSummaryResponse>;
 export const AlertSummaryResponse = z.object({
   id: NonEmptyString,
   alertId: NonEmptyString,
-  timestamp: NonEmptyString.optional(),
+  timestamp: NonEmptyTimestamp.optional(),
   summary: z.string(),
   recommendedActions: z.string().optional(),
   replacements: Replacements,
@@ -70,14 +76,6 @@ export const AlertSummaryBulkCrudActionResults = z.object({
   skipped: z.array(AlertSummaryBulkActionSkipResult),
 });
 
-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 AlertSummaryBulkCrudActionResponse = z.infer<typeof AlertSummaryBulkCrudActionResponse>;
 export const AlertSummaryBulkCrudActionResponse = z.object({
   success: z.boolean().optional(),
@@ -91,18 +89,6 @@ export const AlertSummaryBulkCrudActionResponse = z.object({
   }),
 });
 
-export type BulkActionBase = z.infer<typeof BulkActionBase>;
-export const BulkActionBase = z.object({
-  /**
-   * Query to filter alert summaries
-   */
-  query: z.string().optional(),
-  /**
-   * Array of alert summary IDs
-   */
-  ids: z.array(z.string()).min(1).optional(),
-});
-
 export type AlertSummaryCreateProps = z.infer<typeof AlertSummaryCreateProps>;
 export const AlertSummaryCreateProps = z.object({
   alertId: z.string(),

x-pack/platform/packages/shared/kbn-elastic-assistant-common/docs/openapi/serverless/elastic_assistant_api_2023_10_31.bundled.schema.yaml

@@ -19,7 +19,7 @@ paths:
               type: object
               properties:
                 delete:
-                  $ref: '#/components/schemas/BulkActionBase'
+                  $ref: '../common_attributes.schema.yaml#/components/schemas/BulkActionBase'
                 create:
                   type: array
                   items:
@@ -110,7 +110,7 @@ components:
         alertId:
           $ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
         'timestamp':
-          $ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
+          $ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyTimestamp'
         summary:
           type: string
         recommendedActions:
@@ -158,24 +158,6 @@ components:
         - deleted
         - skipped
 
-
-    BulkCrudActionSummary:
-      type: object
-      properties:
-        failed:
-          type: integer
-        skipped:
-          type: integer
-        succeeded:
-          type: integer
-        total:
-          type: integer
-      required:
-        - failed
-        - skipped
-        - succeeded
-        - total
-
     AlertSummaryBulkCrudActionResponse:
       type: object
       properties:
@@ -193,7 +175,7 @@ components:
             results:
               $ref: '#/components/schemas/AlertSummaryBulkCrudActionResults'
             summary:
-              $ref: '#/components/schemas/BulkCrudActionSummary'
+              $ref: '../common_attributes.schema.yaml#/components/schemas/BulkCrudActionSummary'
             errors:
               type: array
               items:
@@ -204,20 +186,6 @@ components:
       required:
         - attributes
 
-    BulkActionBase:
-      x-inline: true
-      type: object
-      properties:
-        query:
-          type: string
-          description: Query to filter alert summaries
-        ids:
-          type: array
-          description: Array of alert summary IDs
-          minItems: 1
-          items:
-            type: string
-
     AlertSummaryCreateProps:
       type: object
       required:

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

@@ -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<