[8.17] Improves Endpoint exceptions API content (#193172) (#204739)

# Backport

This will backport the following commits from `main` to `8.17`:
- [Improves Endpoint exceptions API content
(#193172)](#193172)

<!--- 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-18T09:45:04Z","message":"Improves
Endpoint exceptions API content (#193172)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#34
by\r\nimproving the Endpoint exceptions API docs content. Adds missing
and\r\nimproves existing operation summaries and operation descriptions
to\r\nadhere to our
[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":"59a0ca244219c701e0c2e80877ff0b6406227c13","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","APIDocs","Team:Detection Rule Management","Team:Detection
Engine"],"number":193172,"url":"https://github.com/elastic/kibana/pull/193172","mergeCommit":{"message":"Improves
Endpoint exceptions API content (#193172)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#34
by\r\nimproving the Endpoint exceptions API docs content. Adds missing
and\r\nimproves existing operation summaries and operation descriptions
to\r\nadhere to our
[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":"59a0ca244219c701e0c2e80877ff0b6406227c13"}},"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/193172","number":193172,"mergeCommit":{"message":"Improves
Endpoint exceptions API content (#193172)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#34
by\r\nimproving the Endpoint exceptions API docs content. Adds missing
and\r\nimproves existing operation summaries and operation descriptions
to\r\nadhere to our
[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":"59a0ca244219c701e0c2e80877ff0b6406227c13"}}]}]
BACKPORT-->

---------

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

oas_docs/output/kibana.yaml

@@ -9880,7 +9880,7 @@ paths:
         - saved objects
   /api/endpoint_list:
     post:
-      description: Creates an endpoint list or does nothing if the list already exists
+      description: Create an endpoint exception list, which groups endpoint exception list items. If an endpoint exception list already exists, an empty response is returned.
       operationId: CreateEndpointList
       responses:
         '200':
@@ -9915,11 +9915,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
           description: Internal server error
-      summary: Creates an endpoint list
+      summary: Create an endpoint exception list
       tags:
         - Security Endpoint Exceptions API
   /api/endpoint_list/items:
     delete:
+      description: Delete an endpoint exception list item using the `id` or `item_id` field.
       operationId: DeleteEndpointListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -9973,10 +9974,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
           description: Internal server error
-      summary: Deletes an endpoint list item
+      summary: Delete an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     get:
+      description: Get the details of an endpoint exception list item using the `id` or `item_id` field.
       operationId: ReadEndpointListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -10032,10 +10034,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
           description: Internal server error
-      summary: Reads an endpoint list item
+      summary: Get an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     post:
+      description: Create an endpoint exception list item, and associate it with the endpoint exception list.
       operationId: CreateEndpointListItem
       requestBody:
         content:
@@ -10110,10 +10113,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
           description: Internal server error
-      summary: Creates an endpoint list item
+      summary: Create an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     put:
+      description: Update an endpoint exception list item using the `id` or `item_id` field.
       operationId: UpdateEndpointListItem
       requestBody:
         content:
@@ -10193,11 +10197,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
           description: Internal server error
-      summary: Updates an endpoint list item
+      summary: Update an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
   /api/endpoint_list/items/_find:
     get:
+      description: Get a list of all endpoint exception list items.
       operationId: FindEndpointListItems
       parameters:
         - description: |
@@ -10297,7 +10302,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
           description: Internal server error
-      summary: Finds endpoint list items
+      summary: Get endpoint exception list items
       tags:
         - Security Endpoint Exceptions API
   /api/endpoint/action:

packages/kbn-securitysolution-endpoint-exceptions-common/api/create_endpoint_list/create_endpoint_list.schema.yaml

@@ -8,8 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: CreateEndpointList
-      summary: Creates an endpoint list
-      description: Creates an endpoint list or does nothing if the list already exists
+      summary: Create an endpoint exception list
+      description: Create an endpoint exception list, which groups endpoint exception list items. If an endpoint exception list already exists, an empty response is returned.
       responses:
         200:
           description: Successful response

packages/kbn-securitysolution-endpoint-exceptions-common/api/create_endpoint_list_item/create_endpoint_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: CreateEndpointListItem
-      summary: Creates an endpoint list item
+      summary: Create an endpoint exception list item
+      description: Create an endpoint exception list item, and associate it with the endpoint exception list.
       requestBody:
         description: Exception list item's properties
         required: true

packages/kbn-securitysolution-endpoint-exceptions-common/api/delete_endpoint_list_item/delete_endpoint_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: DeleteEndpointListItem
-      summary: Deletes an endpoint list item
+      summary: Delete an endpoint exception list item
+      description: Delete an endpoint exception list item using the `id` or `item_id` field.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-endpoint-exceptions-common/api/find_endpoint_list_item/find_endpoint_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: FindEndpointListItems
-      summary: Finds endpoint list items
+      summary: Get endpoint exception list items
+      description: Get a list of all endpoint exception list items.
       parameters:
         - name: filter
           in: query

packages/kbn-securitysolution-endpoint-exceptions-common/api/read_endpoint_list_item/read_endpoint_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: ReadEndpointListItem
-      summary: Reads an endpoint list item
+      summary: Get an endpoint exception list item
+      description: Get the details of an endpoint exception list item using the `id` or `item_id` field.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-endpoint-exceptions-common/api/update_endpoint_list_item/update_endpoint_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: UpdateEndpointListItem
-      summary: Updates an endpoint list item
+      summary: Update an endpoint exception list item
+      description: Update an endpoint exception list item using the `id` or `item_id` field.
       requestBody:
         description: Exception list item's properties
         required: true

packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml

@@ -13,7 +13,10 @@ servers:
 paths:
   /api/endpoint_list:
     post:
-      description: Creates an endpoint list or does nothing if the list already exists
+      description: >-
+        Create an endpoint exception list, which groups endpoint exception list
+        items. If an endpoint exception list already exists, an empty response
+        is returned.
       operationId: CreateEndpointList
       responses:
         '200':
@@ -48,11 +51,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Creates an endpoint list
+      summary: Create an endpoint exception list
       tags:
         - Security Endpoint Exceptions API
   /api/endpoint_list/items:
     delete:
+      description: >-
+        Delete an endpoint exception list item using the `id` or `item_id`
+        field.
       operationId: DeleteEndpointListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -106,10 +112,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Deletes an endpoint list item
+      summary: Delete an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     get:
+      description: >-
+        Get the details of an endpoint exception list item using the `id` or
+        `item_id` field.
       operationId: ReadEndpointListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -165,10 +174,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Reads an endpoint list item
+      summary: Get an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     post:
+      description: >-
+        Create an endpoint exception list item, and associate it with the
+        endpoint exception list.
       operationId: CreateEndpointListItem
       requestBody:
         content:
@@ -243,10 +255,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Creates an endpoint list item
+      summary: Create an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     put:
+      description: >-
+        Update an endpoint exception list item using the `id` or `item_id`
+        field.
       operationId: UpdateEndpointListItem
       requestBody:
         content:
@@ -326,11 +341,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Updates an endpoint list item
+      summary: Update an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
   /api/endpoint_list/items/_find:
     get:
+      description: Get a list of all endpoint exception list items.
       operationId: FindEndpointListItems
       parameters:
         - description: >
@@ -432,7 +448,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Finds endpoint list items
+      summary: Get endpoint exception list items
       tags:
         - Security Endpoint Exceptions API
 components:

packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml

@@ -13,7 +13,10 @@ servers:
 paths:
   /api/endpoint_list:
     post:
-      description: Creates an endpoint list or does nothing if the list already exists
+      description: >-
+        Create an endpoint exception list, which groups endpoint exception list
+        items. If an endpoint exception list already exists, an empty response
+        is returned.
       operationId: CreateEndpointList
       responses:
         '200':
@@ -48,11 +51,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Creates an endpoint list
+      summary: Create an endpoint exception list
       tags:
         - Security Endpoint Exceptions API
   /api/endpoint_list/items:
     delete:
+      description: >-
+        Delete an endpoint exception list item using the `id` or `item_id`
+        field.
       operationId: DeleteEndpointListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -106,10 +112,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Deletes an endpoint list item
+      summary: Delete an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     get:
+      description: >-
+        Get the details of an endpoint exception list item using the `id` or
+        `item_id` field.
       operationId: ReadEndpointListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -165,10 +174,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Reads an endpoint list item
+      summary: Get an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     post:
+      description: >-
+        Create an endpoint exception list item, and associate it with the
+        endpoint exception list.
       operationId: CreateEndpointListItem
       requestBody:
         content:
@@ -243,10 +255,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Creates an endpoint list item
+      summary: Create an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
     put:
+      description: >-
+        Update an endpoint exception list item using the `id` or `item_id`
+        field.
       operationId: UpdateEndpointListItem
       requestBody:
         content:
@@ -326,11 +341,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Updates an endpoint list item
+      summary: Update an endpoint exception list item
       tags:
         - Security Endpoint Exceptions API
   /api/endpoint_list/items/_find:
     get:
+      description: Get a list of all endpoint exception list items.
       operationId: FindEndpointListItems
       parameters:
         - description: >
@@ -432,7 +448,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error
-      summary: Finds endpoint list items
+      summary: Get endpoint exception list items
       tags:
         - Security Endpoint Exceptions API
 components:

x-pack/test/api_integration/services/security_solution_endpoint_exceptions_api.gen.ts

@@ -32,7 +32,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
 
   return {
     /**
-     * Creates an endpoint list or does nothing if the list already exists
+     * Create an endpoint exception list, which groups endpoint exception list items. If an endpoint exception list already exists, an empty response is returned.
      */
     createEndpointList(kibanaSpace: string = 'default') {
       return supertest
@@ -41,6 +41,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
+    /**
+     * Create an endpoint exception list item, and associate it with the endpoint exception list.
+     */
     createEndpointListItem(props: CreateEndpointListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .post(routeWithNamespace('/api/endpoint_list/items', kibanaSpace))
@@ -49,6 +52,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+     * Delete an endpoint exception list item using the `id` or `item_id` field.
+     */
     deleteEndpointListItem(props: DeleteEndpointListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .delete(routeWithNamespace('/api/endpoint_list/items', kibanaSpace))
@@ -57,6 +63,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get a list of all endpoint exception list items.
+     */
     findEndpointListItems(props: FindEndpointListItemsProps, kibanaSpace: string = 'default') {
       return supertest
         .get(routeWithNamespace('/api/endpoint_list/items/_find', kibanaSpace))
@@ -65,6 +74,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get the details of an endpoint exception list item using the `id` or `item_id` field.
+     */
     readEndpointListItem(props: ReadEndpointListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .get(routeWithNamespace('/api/endpoint_list/items', kibanaSpace))
@@ -73,6 +85,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Update an endpoint exception list item using the `id` or `item_id` field.
+     */
     updateEndpointListItem(props: UpdateEndpointListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .put(routeWithNamespace('/api/endpoint_list/items', kibanaSpace))