Improves Exceptions API docs content (#193040)

natasha-moore-elastic · kibanamachine · web-flow · commit c676d2bd72f8 · 2024-09-19T09:13:14.000+01:00
## Summary Resolves elastic/security-docs-internal#33 by improving the Exceptions API docs content. Adds missing and improves existing operation summaries and operation descriptions to adhere to our [OAS standards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs). --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateExceptionList
       x-codegen-enabled: true
-      summary: Creates an exception list
+      summary: Create an exception list
+      description: |
+        An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists.
+        > info
+        > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
       requestBody:
         description: Exception list's properties
         required: true
diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateExceptionListItem
       x-codegen-enabled: true
-      summary: Creates an exception list item
+      summary: Create an exception list item
+      description: |
+        Create an exception item and associate it with the specified exception list.
+        > info
+        > Before creating exception items, you must create an exception list.
       requestBody:
         description: Exception list item's properties
         required: true
diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateRuleExceptionListItems
       x-codegen-enabled: true
-      summary: Creates rule exception list items
+      summary: Create rule exception list items
+      description: Create exception items that apply to a single detection rule. 
       parameters:
         - name: id
           in: path
diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_shared_exceptions_list/create_shared_exceptions_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_shared_exceptions_list/create_shared_exceptions_list.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateSharedExceptionList
       x-codegen-enabled: true
-      summary: Creates a shared exception list
+      summary: Create a shared exception list
+      description: |
+        An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules.
+        > info
+        > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
       requestBody:
         required: true
         content:
diff --git a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DeleteExceptionList
       x-codegen-enabled: true
-      summary: Deletes an exception list
+      summary: Delete an exception list
+      description: Delete an exception list using the `id` or `list_id` field.
       parameters:
         - name: id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DeleteExceptionListItem
       x-codegen-enabled: true
-      summary: Deletes an exception list item
+      summary: Delete an exception list item
+      description: Delete an exception list item using the `id` or `item_id` field.
       parameters:
         - name: id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DuplicateExceptionList
       x-codegen-enabled: true
-      summary: Duplicates an exception list
+      summary: Duplicate an exception list
+      description: Duplicate an existing exception list.
       parameters:
         - name: list_id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ExportExceptionList
       x-codegen-enabled: true
-      summary: Exports an exception list
-      description: Exports an exception list and its associated items to an .ndjson file
+      summary: Export an exception list
+      description: Export an exception list and its associated items to an NDJSON file.
       parameters:
         - name: id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: FindExceptionListItems
       x-codegen-enabled: true
-      summary: Finds exception list items
+      summary: Get exception list items
+      description: Get a list of all exception list items in the specified list.
       parameters:
         - name: list_id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: FindExceptionLists
       x-codegen-enabled: true
-      summary: Finds exception lists
+      summary: Get exception lists
+      description: Get a list of all exception lists.
       parameters:
         - name: filter
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ImportExceptionList
       x-codegen-enabled: true
-      summary: Imports an exception list
-      description: Imports an exception list and associated items
+      summary: Import an exception list
+      description: Import an exception list and its associated items from an NDJSON file.
       requestBody:
         required: true
         content:
diff --git a/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts
@@ -98,6 +98,12 @@ export class Client {
     this.kbnClient = options.kbnClient;
     this.log = options.log;
   }
+  /**
+    * An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists.
+> info
+> All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
+
+    */
   async createExceptionList(props: CreateExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateExceptionList`);
     return this.kbnClient
@@ -111,6 +117,12 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * Create an exception item and associate it with the specified exception list.
+> info
+> Before creating exception items, you must create an exception list.
+
+    */
   async createExceptionListItem(props: CreateExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateExceptionListItem`);
     return this.kbnClient
@@ -124,6 +136,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Create exception items that apply to a single detection rule.
+   */
   async createRuleExceptionListItems(props: CreateRuleExceptionListItemsProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateRuleExceptionListItems`);
     return this.kbnClient
@@ -137,6 +152,12 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules.
+> info
+> All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
+
+    */
   async createSharedExceptionList(props: CreateSharedExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateSharedExceptionList`);
     return this.kbnClient
@@ -150,6 +171,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete an exception list using the `id` or `list_id` field.
+   */
   async deleteExceptionList(props: DeleteExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteExceptionList`);
     return this.kbnClient
@@ -164,6 +188,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete an exception list item using the `id` or `item_id` field.
+   */
   async deleteExceptionListItem(props: DeleteExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteExceptionListItem`);
     return this.kbnClient
@@ -178,6 +205,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Duplicate an existing exception list.
+   */
   async duplicateExceptionList(props: DuplicateExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API DuplicateExceptionList`);
     return this.kbnClient
@@ -193,7 +223,7 @@ export class Client {
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Exports an exception list and its associated items to an .ndjson file
+   * Export an exception list and its associated items to an NDJSON file.
    */
   async exportExceptionList(props: ExportExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API ExportExceptionList`);
@@ -209,6 +239,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a list of all exception list items in the specified list.
+   */
   async findExceptionListItems(props: FindExceptionListItemsProps) {
     this.log.info(`${new Date().toISOString()} Calling API FindExceptionListItems`);
     return this.kbnClient
@@ -223,6 +256,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a list of all exception lists.
+   */
   async findExceptionLists(props: FindExceptionListsProps) {
     this.log.info(`${new Date().toISOString()} Calling API FindExceptionLists`);
     return this.kbnClient
@@ -238,7 +274,7 @@ export class Client {
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Imports an exception list and associated items
+   * Import an exception list and its associated items from an NDJSON file.
    */
   async importExceptionList(props: ImportExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API ImportExceptionList`);
@@ -254,6 +290,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of an exception list using the `id` or `list_id` field.
+   */
   async readExceptionList(props: ReadExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadExceptionList`);
     return this.kbnClient
@@ -268,6 +307,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of an exception list item using the `id` or `item_id` field.
+   */
   async readExceptionListItem(props: ReadExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadExceptionListItem`);
     return this.kbnClient
@@ -282,6 +324,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a summary of the specified exception list.
+   */
   async readExceptionListSummary(props: ReadExceptionListSummaryProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadExceptionListSummary`);
     return this.kbnClient
@@ -296,6 +341,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Update an exception list using the `id` or `list_id` field.
+   */
   async updateExceptionList(props: UpdateExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API UpdateExceptionList`);
     return this.kbnClient
@@ -309,6 +357,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Update an exception list item using the `id` or `item_id` field.
+   */
   async updateExceptionListItem(props: UpdateExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API UpdateExceptionListItem`);
     return this.kbnClient
diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadExceptionList
       x-codegen-enabled: true
-      summary: Retrieves an exception list using its `id` or `list_id` field
+      summary: Get exception list details
+      description: Get the details of an exception list using the `id` or `list_id` field.
       parameters:
         - name: id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadExceptionListItem
       x-codegen-enabled: true
-      summary: Gets an exception list item
+      summary: Get an exception list item
+      description: Get the details of an exception list item using the `id` or `item_id` field.
       parameters:
         - name: id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadExceptionListSummary
       x-codegen-enabled: true
-      summary: Retrieves an exception list summary
+      summary: Get an exception list summary
+      description: Get a summary of the specified exception list.
       parameters:
         - name: id
           in: query
diff --git a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: UpdateExceptionList
       x-codegen-enabled: true
-      summary: Updates an exception list
+      summary: Update an exception list
+      description: Update an exception list using the `id` or `list_id` field.
       requestBody:
         description: Exception list's properties
         required: true
diff --git a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: UpdateExceptionListItem
       x-codegen-enabled: true
-      summary: Updates an exception list item
+      summary: Update an exception list item
+      description: Update an exception list item using the `id` or `item_id` field.
       requestBody:
         description: Exception list item's properties
         required: true
diff --git a/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
diff --git a/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
diff --git a/x-pack/test/api_integration/services/security_solution_exceptions_api.gen.ts b/x-pack/test/api_integration/services/security_solution_exceptions_api.gen.ts
