[8.16] Improves Exceptions API docs content (elastic#193040) (elastic…

…#204733)

# Backport

This will backport the following commits from `main` to `8.16`:
- [Improves Exceptions API docs content
(elastic#193040)](elastic#193040)

<!--- Backport version: 8.9.8 -->

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

<!--BACKPORT
[{"author":{"name":"natasha-moore-elastic","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-09-19T08:13:14Z","message":"Improves
Exceptions API docs content (elastic#193040)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#33
by\r\nimproving the Exceptions API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"c676d2bd72f87fceecd8d459335ed56e36acf661","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","backport:skip","v9.0.0","docs","Team:Detections
and Resp","Team: SecuritySolution","APIDocs","Team:Detection Rule
Management","Team:Detection
Engine"],"number":193040,"url":"https://github.com/elastic/kibana/pull/193040","mergeCommit":{"message":"Improves
Exceptions API docs content (elastic#193040)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#33
by\r\nimproving the Exceptions API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"c676d2bd72f87fceecd8d459335ed56e36acf661"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/193040","number":193040,"mergeCommit":{"message":"Improves
Exceptions API docs content (elastic#193040)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#33
by\r\nimproving the Exceptions API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"c676d2bd72f87fceecd8d459335ed56e36acf661"}}]}]
BACKPORT-->

---------

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

oas_docs/output/kibana.yaml

@@ -8781,6 +8781,7 @@ paths:
         - Security Detections API
   /api/detection_engine/rules/{id}/exceptions:
     post:
+      description: Create exception items that apply to a single detection rule.
       operationId: CreateRuleExceptionListItems
       parameters:
         - description: Detection rule's identifier
@@ -8838,7 +8839,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates rule exception list items
+      summary: Create rule exception list items
       tags:
         - Security Exceptions API
   /api/detection_engine/rules/prepackaged:
@@ -10869,6 +10870,7 @@ paths:
         - Security Entity Analytics API
   /api/exception_lists:
     delete:
+      description: Delete an exception list using the `id` or `list_id` field.
       operationId: DeleteExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -10928,10 +10930,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list
+      summary: Delete an exception list
       tags:
         - Security Exceptions API
     get:
+      description: Get the details of an exception list using the `id` or `list_id` field.
       operationId: ReadExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -10991,10 +10994,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list using its `id` or `list_id` field
+      summary: Get exception list details
       tags:
         - Security Exceptions API
     post:
+      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.
       operationId: CreateExceptionList
       requestBody:
         content:
@@ -11068,10 +11075,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list
+      summary: Create an exception list
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list using the `id` or `list_id` field.
       operationId: UpdateExceptionList
       requestBody:
         content:
@@ -11148,11 +11156,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list
+      summary: Update an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_duplicate:
     post:
+      description: Duplicate an existing exception list.
       operationId: DuplicateExceptionList
       parameters:
         - description: Exception list's human identifier
@@ -11215,12 +11224,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Duplicates an exception list
+      summary: Duplicate an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_export:
     post:
-      description: Exports an exception list and its associated items to an .ndjson file
+      description: Export an exception list and its associated items to an NDJSON file.
       operationId: ExportExceptionList
       parameters:
         - description: Exception list's identifier
@@ -11291,11 +11300,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Exports an exception list
+      summary: Export an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_find:
     get:
+      description: Get a list of all exception lists.
       operationId: FindExceptionLists
       parameters:
         - description: |
@@ -11403,12 +11413,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception lists
+      summary: Get exception lists
       tags:
         - Security Exceptions API
   /api/exception_lists/_import:
     post:
-      description: Imports an exception list and associated items
+      description: Import an exception list and its associated items from an NDJSON file.
       operationId: ImportExceptionList
       parameters:
         - description: |
@@ -11512,11 +11522,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Imports an exception list
+      summary: Import an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/items:
     delete:
+      description: Delete an exception list item using the `id` or `item_id` field.
       operationId: DeleteExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -11576,10 +11587,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list item
+      summary: Delete an exception list item
       tags:
         - Security Exceptions API
     get:
+      description: Get the details of an exception list item using the `id` or `item_id` field.
       operationId: ReadExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -11639,10 +11651,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Gets an exception list item
+      summary: Get an exception list item
       tags:
         - Security Exceptions API
     post:
+      description: |
+        Create an exception item and associate it with the specified exception list.
+        > info
+        > Before creating exception items, you must create an exception list.
       operationId: CreateExceptionListItem
       requestBody:
         content:
@@ -11726,10 +11742,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list item
+      summary: Create an exception list item
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list item using the `id` or `item_id` field.
       operationId: UpdateExceptionListItem
       requestBody:
         content:
@@ -11817,11 +11834,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list item
+      summary: Update an exception list item
       tags:
         - Security Exceptions API
   /api/exception_lists/items/_find:
     get:
+      description: Get a list of all exception list items in the specified list.
       operationId: FindExceptionListItems
       parameters:
         - description: List's id
@@ -11949,11 +11967,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception list items
+      summary: Get exception list items
       tags:
         - Security Exceptions API
   /api/exception_lists/summary:
     get:
+      description: Get a summary of the specified exception list.
       operationId: ReadExceptionListSummary
       parameters:
         - description: Exception list's identifier generated upon creation
@@ -12032,11 +12051,15 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list summary
+      summary: Get an exception list summary
       tags:
         - Security Exceptions API
   /api/exceptions/shared:
     post:
+      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.
       operationId: CreateSharedExceptionList
       requestBody:
         content:
@@ -12091,7 +12114,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates a shared exception list
+      summary: Create a shared exception list
       tags:
         - Security Exceptions API
   /api/fleet/agent_download_sources:

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

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

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

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:

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

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

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

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

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

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

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: