[8.18][Detection Engine][API Docs] Update request/response examples for value lists APIs (#205957)

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

@@ -891,8 +891,23 @@ components:
     FindEndpointListItemsFilter:
       $ref: '#/components/schemas/NonEmptyString'
     ListId:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Value list's identifier.
+      example: 21b01cfb-058d-44b9-838c-282be16c91cd
+      format: nonempty
+      minLength: 1
+      type: string
     ListType:
+      description: >
+        Specifies the Elasticsearch data type of excludes the list container
+        holds. Some common examples:
+
+
+        - `keyword`: Many ECS fields are Elasticsearch keywords
+
+        - `ip`: IP addresses
+
+        - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR
+        notation)
       enum:
         - binary
         - boolean

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

@@ -891,8 +891,23 @@ components:
     FindEndpointListItemsFilter:
       $ref: '#/components/schemas/NonEmptyString'
     ListId:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Value list's identifier.
+      example: 21b01cfb-058d-44b9-838c-282be16c91cd
+      format: nonempty
+      minLength: 1
+      type: string
     ListType:
+      description: >
+        Specifies the Elasticsearch data type of excludes the list container
+        holds. Some common examples:
+
+
+        - `keyword`: Many ECS fields are Elasticsearch keywords
+
+        - `ip`: IP addresses
+
+        - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR
+        notation)
       enum:
         - binary
         - boolean

x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml

@@ -3259,8 +3259,23 @@ components:
       example: 'exception-list.attributes.name:%Detection%20List'
       type: string
     ListId:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Value list's identifier.
+      example: 21b01cfb-058d-44b9-838c-282be16c91cd
+      format: nonempty
+      minLength: 1
+      type: string
     ListType:
+      description: >
+        Specifies the Elasticsearch data type of excludes the list container
+        holds. Some common examples:
+
+
+        - `keyword`: Many ECS fields are Elasticsearch keywords
+
+        - `ip`: IP addresses
+
+        - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR
+        notation)
       enum:
         - binary
         - boolean

x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml

@@ -3259,8 +3259,23 @@ components:
       example: 'exception-list.attributes.name:%Detection%20List'
       type: string
     ListId:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Value list's identifier.
+      example: 21b01cfb-058d-44b9-838c-282be16c91cd
+      format: nonempty
+      minLength: 1
+      type: string
     ListType:
+      description: >
+        Specifies the Elasticsearch data type of excludes the list container
+        holds. Some common examples:
+
+
+        - `keyword`: Many ECS fields are Elasticsearch keywords
+
+        - `ip`: IP addresses
+
+        - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR
+        notation)
       enum:
         - binary
         - boolean

x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts

@@ -10,7 +10,7 @@
  * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator.
  *
  * info:
- *   title: Create list API endpoint
+ *   title: Create value list API endpoint
  *   version: 2023-10-31
  */
 
@@ -21,6 +21,8 @@ import {
   ListName,
   ListDescription,
   ListType,
+  ListSerializer,
+  ListDeserializer,
   ListMetadata,
 } from '../model/list_common.gen';
 import { List } from '../model/list_schemas.gen';
@@ -31,8 +33,8 @@ export const CreateListRequestBody = z.object({
   name: ListName,
   description: ListDescription,
   type: ListType,
-  serializer: z.string().optional(),
-  deserializer: z.string().optional(),
+  serializer: ListSerializer.optional(),
+  deserializer: ListDeserializer.optional(),
   meta: ListMetadata.optional(),
   version: z.number().int().min(1).optional().default(1),
 });

x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml

@@ -1,17 +1,17 @@
 openapi: 3.0.0
 info:
-  title: Create list API endpoint
+  title: Create value list API endpoint
   version: '2023-10-31'
 paths:
   /api/lists:
     post:
       x-labels: [serverless, ess]
       operationId: CreateList
       x-codegen-enabled: true
-      summary: Create a list
-      description: Create a new list.
+      summary: Create a value list
+      description: Create a new value list.
       requestBody:
-        description: List's properties
+        description: Value list's properties
         required: true
         content:
           application/json:
@@ -27,9 +27,9 @@ paths:
                 type:
                   $ref: '../model/list_common.schema.yaml#/components/schemas/ListType'
                 serializer:
-                  type: string
+                  $ref: '../model/list_common.schema.yaml#/components/schemas/ListSerializer'
                 deserializer:
-                  type: string
+                  $ref: '../model/list_common.schema.yaml#/components/schemas/ListDeserializer'
                 meta:
                   $ref: '../model/list_common.schema.yaml#/components/schemas/ListMetadata'
                 version:
@@ -40,13 +40,104 @@ paths:
                 - name
                 - description
                 - type
+            examples:
+              ip:
+                value:
+                  id: ip_list
+                  name: Simple list with ips
+                  description: This list describes bad internet ips
+                  type: ip
+              ip_range:
+                value:
+                  id: ip_range_list
+                  name: Simple list with ip ranges
+                  description: This list has ip ranges
+                  type: ip_range
+              keyword:
+                value:
+                  id: keyword_list
+                  name: Simple list with a keyword
+                  description: This list describes bad host names
+                  type: keyword
+              keyword_custom_format:
+                value:
+                  id: keyword_custom_format_list
+                  name: Simple list with a keyword using a custom format
+                  description: This parses the first found ipv4 only
+                  serializer: (?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))
+                  deserializer: '{{value}}'
+                  type: keyword
+
       responses:
         200:
           description: Successful response
           content:
             application/json:
               schema:
                 $ref: '../model/list_schemas.schema.yaml#/components/schemas/List'
+              examples:
+                ip:
+                  value:
+                    id: ip_list
+                    type: ip
+                    name: Simple list with ips
+                    description: This list describes bad internet ips
+                    immutable: false
+                    '@timestamp': 2025-01-08T04:47:34.273Z
+                    version: 1
+                    _version: WzAsMV0=
+                    tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899
+                    created_at: 2025-01-08T04:47:34.273Z
+                    created_by: elastic
+                    updated_at: 2025-01-08T04:47:34.273Z
+                    updated_by: elastic
+                ip_range:
+                  value:
+                    id: ip_range_list
+                    type: ip_range
+                    name: Simple list with ip ranges
+                    description: This list has ip ranges
+                    immutable: false
+                    '@timestamp': 2025-01-09T18:23:52.241Z
+                    version: 1
+                    _version: WzAsMV0=
+                    tie_breaker_id: 74aebdaf-601f-4940-b351-155728ff7003
+                    created_at: 2025-01-09T18:23:52.241Z
+                    created_by: elastic
+                    updated_at: 2025-01-09T18:23:52.241Z
+                    updated_by: elastic
+                keyword:
+                  value:
+                    id: keyword_list
+                    type: keyword
+                    name: Simple list with a keyword
+                    description: This list describes bad host names
+                    immutable: false
+                    '@timestamp': 2025-01-09T18:24:55.786Z
+                    version: 1
+                    _version: WzEsMV0=
+                    tie_breaker_id: f7e7dbaa-daf7-4c9a-a3dc-56643923ef68
+                    created_at: 2025-01-09T18:24:55.786Z
+                    created_by: elastic
+                    updated_at: 2025-01-09T18:24:55.786Z
+                    updated_by: elastic
+                keyword_custom_format:
+                  value:
+                    id: keyword_custom_format_list
+                    type: keyword
+                    name: Simple list with a keyword using a custom format
+                    description: This parses the first found ipv4 only
+                    serializer: '(?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))'
+                    deserializer: '{{value}}'
+                    immutable: false
+                    '@timestamp': 2025-01-09T18:25:39.604Z
+                    version: 1
+                    _version: WzIsMV0=
+                    tie_breaker_id: 8247ae63-b780-47b8-9a89-948b643e9ec2
+                    created_at: 2025-01-09T18:25:39.604Z
+                    created_by: elastic
+                    updated_at: 2025-01-09T18:25:39.604Z
+                    updated_by: elastic
         400:
           description: Invalid input data response
           content:
@@ -55,27 +146,54 @@ paths:
                 oneOf:
                   - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
                   - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+              examples:
+                notFound:
+                  value:
+                    message: To create a list, the data stream must exist first. Data stream \".lists-default\" does not exist
+                    status_code: 400
         401:
           description: Unsuccessful authentication response
           content:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+              examples:
+                unauthorized:
+                  value:
+                    statusCode: 401
+                    error: Unauthorized
+                    message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]'
         403:
           description: Not enough privileges response
           content:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+              examples:
+                forbidden:
+                  value:
+                    statusCode: 403
+                    error: Forbidden
+                    message: 'API [POST /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]'
         409:
           description: List already exists response
           content:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+              examples:
+                alreadyExists:
+                  value:
+                    message: 'list id: "keyword_custom_format_list" already exists'
+                    status_code: 409
         500:
           description: Internal server error response
           content:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+              examples:
+                serverError:
+                  value:
+                    message: Internal Server Error
+                    status_code: 500

x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml

@@ -35,6 +35,13 @@ paths:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+              examples:
+                unauthorized:
+                  value:
+                    statusCode: 401
+                    error: Unauthorized
+                    message: |
+                      [security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]
         403:
           description: Not enough privileges response
           content:
@@ -47,9 +54,19 @@ paths:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+              examples:
+                alreadyExists:
+                  value:
+                    message: 'data stream: \".lists-default\" and \".items-default\" already exists'
+                    status_code: 409
         500:
           description: Internal server error response
           content:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+              examples:
+                serverError:
+                  value:
+                    message: Internal Server Error
+                    status_code: 500

x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts

@@ -10,7 +10,7 @@
  * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator.
  *
  * info:
- *   title: Create list item API endpoint
+ *   title: Create value list item API endpoint
  *   version: 2023-10-31
  */
 
@@ -26,7 +26,7 @@ export const CreateListItemRequestBody = z.object({
   value: ListItemValue,
   meta: ListItemMetadata.optional(),
   /**
-   * Determines when changes made by the request are made visible to search
+   * Determines when changes made by the request are made visible to search.
    */
   refresh: z.enum(['true', 'false', 'wait_for']).optional(),
 });