Improves Lists API docs content (elastic#192504)

## Summary Resolves elastic/security-docs-internal#32 by improving the Lists 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). Note: Couldn’t add description for the GET /api/lists/privileges operation, since it's not documented in [ESS API docs](https://www.elastic.co/guide/en/security/8.15/security-apis.html). --------- Co-authored-by: kibanamachine <[email protected]>
elena-shostak · Sep 17, 2024 · 5c58979 · 5c58979
1 parent a87e7e8
commit 5c58979
Show file tree

Hide file tree

Showing 22 changed files with 295 additions and 66 deletions.
diff --git a/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateList
       x-codegen-enabled: true
-      summary: Creates a list
+      summary: Create a list
+      description: Create a new list.
       requestBody:
         description: List's properties
         required: true

diff --git a/...ges/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml b/...ges/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateListIndex
       x-codegen-enabled: true
-      summary: Creates necessary list data streams
+      summary: Create list data streams
+      description: Create `.lists` and `.items` data streams in the relevant space.
       responses:
         200:
           description: Successful response

diff --git a/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml
@@ -8,7 +8,13 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateListItem
       x-codegen-enabled: true
-      summary: Creates a list item
+      summary: Create a list item
+      description: |
+        Create a list item and associate it with the specified list.
+        
+        All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
+        > info
+        > Before creating a list item, you must create a list.
       requestBody:
         description: List item's properties
         required: true

diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: DeleteList
       x-codegen-enabled: true
-      summary: Deletes a list
+      summary: Delete a list
+      description: |
+        Delete a list using the list ID.
+        > info
+        > When you delete a list, all of its list items are also deleted.
       parameters:
         - name: id
           in: query

diff --git a/...ges/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml b/...ges/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DeleteListIndex
       x-codegen-enabled: true
-      summary: Deletes list data streams
+      summary: Delete list data streams
+      description: Delete the `.lists` and `.items` data streams.
       responses:
         200:
           description: Successful response

diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DeleteListItem
       x-codegen-enabled: true
-      summary: Deletes a list item
+      summary: Delete a list item
+      description: Delete a list item using its `id`, or its `list_id` and `value` fields.
       parameters:
         - name: id
           in: query

diff --git a/...ges/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml b/...ges/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ExportListItems
       x-codegen-enabled: true
-      summary: Exports list items
-      description: Exports list item values from the specified list
+      summary: Export list items
+      description: Export list item values from the specified list.
       parameters:
         - name: list_id
           in: query

diff --git a/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml b/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: FindListItems
       x-codegen-enabled: true
-      summary: Finds list items
+      summary: Get list items
+      description: Get all list items in the specified list.
       parameters:
         - name: list_id
           in: query

diff --git a/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml b/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: FindLists
       x-codegen-enabled: true
-      summary: Finds lists
+      summary: Get lists
+      description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
       parameters:
         - name: page
           in: query

diff --git a/...ges/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml b/...ges/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml
@@ -8,9 +8,9 @@ paths:
       x-labels: [serverless, ess]
       operationId: ImportListItems
       x-codegen-enabled: true
-      summary: Imports list items
+      summary: Import list items
       description: |
-        Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
+        Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.
 
         You can import items to a new or existing list.
       requestBody:

diff --git a/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: PatchList
       x-codegen-enabled: true
-      summary: Patches a list
+      summary: Patch a list
+      description: Update specific fields of an existing list using the list ID.
       requestBody:
         description: List's properties
         required: true

diff --git a/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: PatchListItem
       x-codegen-enabled: true
-      summary: Patches a list item
+      summary: Patch a list item
+      description: Update specific fields of an existing list item using the list item ID.
       requestBody:
         description: List item's properties
         required: true

diff --git a/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts b/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts
@@ -77,6 +77,9 @@ export class Client {
     this.kbnClient = options.kbnClient;
     this.log = options.log;
   }
+  /**
+   * Create a new list.
+   */
   async createList(props: CreateListProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateList`);
     return this.kbnClient
@@ -90,6 +93,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Create `.lists` and `.items` data streams in the relevant space.
+   */
   async createListIndex() {
     this.log.info(`${new Date().toISOString()} Calling API CreateListIndex`);
     return this.kbnClient
@@ -102,6 +108,14 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * Create a list item and associate it with the specified list.
+
+All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
+> info
+> Before creating a list item, you must create a list.
+
+    */
   async createListItem(props: CreateListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateListItem`);
     return this.kbnClient
@@ -115,6 +129,12 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * Delete a list using the list ID.
+> info
+> When you delete a list, all of its list items are also deleted.
+
+    */
   async deleteList(props: DeleteListProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteList`);
     return this.kbnClient
@@ -129,6 +149,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete the `.lists` and `.items` data streams.
+   */
   async deleteListIndex() {
     this.log.info(`${new Date().toISOString()} Calling API DeleteListIndex`);
     return this.kbnClient
@@ -141,6 +164,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete a list item using its `id`, or its `list_id` and `value` fields.
+   */
   async deleteListItem(props: DeleteListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteListItem`);
     return this.kbnClient
@@ -156,7 +182,7 @@ export class Client {
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Exports list item values from the specified list
+   * Export list item values from the specified list.
    */
   async exportListItems(props: ExportListItemsProps) {
     this.log.info(`${new Date().toISOString()} Calling API ExportListItems`);
@@ -172,6 +198,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get all list items in the specified list.
+   */
   async findListItems(props: FindListItemsProps) {
     this.log.info(`${new Date().toISOString()} Calling API FindListItems`);
     return this.kbnClient
@@ -186,6 +215,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
+   */
   async findLists(props: FindListsProps) {
     this.log.info(`${new Date().toISOString()} Calling API FindLists`);
     return this.kbnClient
@@ -201,7 +233,7 @@ export class Client {
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-    * Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
+    * Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.
 
 You can import items to a new or existing list.
 
@@ -220,6 +252,9 @@ You can import items to a new or existing list.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Update specific fields of an existing list using the list ID.
+   */
   async patchList(props: PatchListProps) {
     this.log.info(`${new Date().toISOString()} Calling API PatchList`);
     return this.kbnClient
@@ -233,6 +268,9 @@ You can import items to a new or existing list.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Update specific fields of an existing list item using the list item ID.
+   */
   async patchListItem(props: PatchListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API PatchListItem`);
     return this.kbnClient
@@ -246,6 +284,9 @@ You can import items to a new or existing list.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of a list using the list ID.
+   */
   async readList(props: ReadListProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadList`);
     return this.kbnClient
@@ -260,6 +301,9 @@ You can import items to a new or existing list.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Verify that `.lists` and `.items` data streams exist.
+   */
   async readListIndex() {
     this.log.info(`${new Date().toISOString()} Calling API ReadListIndex`);
     return this.kbnClient
@@ -272,6 +316,9 @@ You can import items to a new or existing list.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of a list item.
+   */
   async readListItem(props: ReadListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadListItem`);
     return this.kbnClient
@@ -298,6 +345,12 @@ You can import items to a new or existing list.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted.
+> info
+> You cannot modify the `id` value.
+
+    */
   async updateList(props: UpdateListProps) {
     this.log.info(`${new Date().toISOString()} Calling API UpdateList`);
     return this.kbnClient
@@ -311,6 +364,12 @@ You can import items to a new or existing list.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.
+> info
+> You cannot modify the `id` value.
+
+    */
   async updateListItem(props: UpdateListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API UpdateListItem`);
     return this.kbnClient

diff --git a/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadList
       x-codegen-enabled: true
-      summary: Retrieves a list using its id field
+      summary: Get list details
+      description: Get the details of a list using the list ID.
       parameters:
         - name: id
           in: query

diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml b/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadListIndex
       x-codegen-enabled: true
-      summary: Get list data stream existence status
+      summary: Get status of list data streams 
+      description: Verify that `.lists` and `.items` data streams exist.
       responses:
         200:
           description: Successful response

diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadListItem
       x-codegen-enabled: true
-      summary: Gets a list item
+      summary: Get a list item
+      description: Get the details of a list item.
       parameters:
         - name: id
           in: query

diff --git a/...n-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml b/...n-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml
@@ -8,7 +8,7 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadListPrivileges
       x-codegen-enabled: true
-      summary: Gets list privileges
+      summary: Get list privileges
       responses:
         200:
           description: Successful response

diff --git a/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: UpdateList
       x-codegen-enabled: true
-      summary: Updates a list
+      summary: Update a list
+      description: |
+        Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted.
+        > info
+        > You cannot modify the `id` value.
       requestBody:
         description: List's properties
         required: true

diff --git a/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: UpdateListItem
       x-codegen-enabled: true
-      summary: Updates a list item
+      summary: Update a list item
+      description: |
+        Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.
+        > info
+        > You cannot modify the `id` value.
       requestBody:
         description: List item's properties
         required: true