[Entity Analytics] Tidy Asset Criticality API docs (elastic#190037)

**Addresses:** elastic#190038 ## Summary Tidy the asset criticality API docs after reviewing the doc previews for [Serverless](https://bump.sh/per-solution-example/doc/security-solution-api-playground) and [ESS](https://bump.sh/per-solution-example/doc/security-solution-api-playground-ess) --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
yuliacech · Aug 13, 2024 · 919844d · 919844d
1 parent bd5927f
commit 919844d
Show file tree

Hide file tree

Showing 9 changed files with 64 additions and 23 deletions.
diff --git a/...n/common/api/entity_analytics/asset_criticality/bulk_upload_asset_criticality.schema.yaml b/...n/common/api/entity_analytics/asset_criticality/bulk_upload_asset_criticality.schema.yaml
@@ -1,3 +1,4 @@
+# ⚠️ Updating this file? Also update the public API docs at https://github.com/elastic/security-docs/tree/main/docs/advanced-entity-analytics/api
 openapi: 3.0.0
 info:
   version: '2023-10-31'
@@ -8,7 +9,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: BulkUpsertAssetCriticalityRecords
-      summary: Bulk upsert asset criticality data, creating or updating records as needed
+      summary: Bulk Upsert Asset Criticality Records
+      description: Bulk upsert up to 1000 asset criticality records, creating or updating them as needed.
       requestBody:
         content:
           application/json:

diff --git a/...lution/common/api/entity_analytics/asset_criticality/create_asset_criticality.schema.yaml b/...lution/common/api/entity_analytics/asset_criticality/create_asset_criticality.schema.yaml
@@ -1,3 +1,4 @@
+# ⚠️ Updating this file? Also update the public API docs at https://github.com/elastic/security-docs/tree/main/docs/advanced-entity-analytics/api
 openapi: 3.0.0
 info:
   version: '2023-10-31'
@@ -8,7 +9,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: CreateAssetCriticalityRecord
-      summary: Create Criticality Record
+      summary: Upsert Criticality Record
+      description: Create or update a criticality record for a specific asset.
       requestBody:
         required: true
         content:

diff --git a/...ty_solution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.gen.ts b/...ty_solution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.gen.ts
@@ -44,8 +44,11 @@ export type DeleteAssetCriticalityRecordResponse = z.infer<
 >;
 export const DeleteAssetCriticalityRecordResponse = z.object({
   /**
-   * If the record was deleted. If false the record did not exist.
+   * True if the record was deleted or false if the record did not exist.
    */
   deleted: z.boolean(),
+  /**
+   * The deleted record if it existed.
+   */
   record: AssetCriticalityRecord.optional(),
 });
diff --git a/...lution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.schema.yaml b/...lution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.schema.yaml
@@ -1,3 +1,4 @@
+# ⚠️ Updating this file? Also update the public API docs at https://github.com/elastic/security-docs/tree/main/docs/advanced-entity-analytics/api
 openapi: 3.0.0
 info:
   version: '2023-10-31'
@@ -9,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: DeleteAssetCriticalityRecord
       summary: Delete Criticality Record
+      description: Delete the asset criticality record for a specific asset if it exists.
       parameters:
         - name: id_value
           in: query
@@ -40,8 +42,9 @@ paths:
                 properties:
                   deleted:
                     type: boolean
-                    description: If the record was deleted. If false the record did not exist.
+                    description: True if the record was deleted or false if the record did not exist.
                   record:
+                    description: The deleted record if it existed.
                     $ref: './common.schema.yaml#/components/schemas/AssetCriticalityRecord'
                 required:
                   - deleted

diff --git a/..._solution/common/api/entity_analytics/asset_criticality/get_asset_criticality.schema.yaml b/..._solution/common/api/entity_analytics/asset_criticality/get_asset_criticality.schema.yaml
@@ -1,3 +1,4 @@
+# ⚠️ Updating this file? Also update the public API docs at https://github.com/elastic/security-docs/tree/main/docs/advanced-entity-analytics/api
 openapi: 3.0.0
 info:
   version: '2023-10-31'
@@ -9,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: GetAssetCriticalityRecord
       summary: Get Criticality Record
+      description: Get the criticality record for a specific asset.
       parameters:
         - name: id_value
           in: query

diff --git a/...solution/common/api/entity_analytics/asset_criticality/list_asset_criticality.schema.yaml b/...solution/common/api/entity_analytics/asset_criticality/list_asset_criticality.schema.yaml
@@ -1,14 +1,16 @@
+# ⚠️ Updating this file? Also update the public API docs at https://github.com/elastic/security-docs/tree/main/docs/advanced-entity-analytics/api
 openapi: 3.0.0
 info:
   version: '2023-10-31'
   title: Asset Criticality List Schema
 paths:
   /api/asset_criticality/list:
-    post:
+    get:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: FindAssetCriticalityRecords
-      summary: List asset criticality data, filtering and sorting as needed
+      summary: List Asset Criticality Records
+      description: List asset criticality records, paging, sorting and filtering as needed.
       parameters:
         - name: sort_field
           in: query

diff --git a/...on/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/...on/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
@@ -13,6 +13,7 @@ servers:
 paths:
   /api/asset_criticality:
     delete:
+      description: Delete the asset criticality record for a specific asset if it exists.
       operationId: DeleteAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
@@ -45,11 +46,12 @@ paths:
                 properties:
                   deleted:
                     description: >-
-                      If the record was deleted. If false the record did not
-                      exist.
+                      True if the record was deleted or false if the record did
+                      not exist.
                     type: boolean
                   record:
                     $ref: '#/components/schemas/AssetCriticalityRecord'
+                    description: The deleted record if it existed.
                 required:
                   - deleted
           description: Successful response
@@ -59,6 +61,7 @@ paths:
       tags:
         - Security Solution Entity Analytics API
     get:
+      description: Get the criticality record for a specific asset.
       operationId: GetAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
@@ -89,6 +92,7 @@ paths:
       tags:
         - Security Solution Entity Analytics API
     post:
+      description: Create or update a criticality record for a specific asset.
       operationId: CreateAssetCriticalityRecord
       requestBody:
         content:
@@ -115,11 +119,14 @@ paths:
           description: Successful response
         '400':
           description: Invalid request
-      summary: Create Criticality Record
+      summary: Upsert Criticality Record
       tags:
         - Security Solution Entity Analytics API
   /api/asset_criticality/bulk:
     post:
+      description: >-
+        Bulk upsert up to 1000 asset criticality records, creating or updating
+        them as needed.
       operationId: BulkUpsertAssetCriticalityRecords
       requestBody:
         content:
@@ -170,13 +177,12 @@ paths:
           description: Bulk upload successful
         '413':
           description: File too large
-      summary: >-
-        Bulk upsert asset criticality data, creating or updating records as
-        needed
+      summary: Bulk Upsert Asset Criticality Records
       tags:
         - Security Solution Entity Analytics API
   /api/asset_criticality/list:
-    post:
+    get:
+      description: 'List asset criticality records, paging, sorting and filtering as needed.'
       operationId: FindAssetCriticalityRecords
       parameters:
         - description: The field to sort by.
@@ -247,7 +253,7 @@ paths:
                   - per_page
                   - total
           description: Bulk upload successful
-      summary: 'List asset criticality data, filtering and sorting as needed'
+      summary: List Asset Criticality Records
       tags:
         - Security Solution Entity Analytics API
 components:

diff --git a/.../openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/.../openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
@@ -13,6 +13,7 @@ servers:
 paths:
   /api/asset_criticality:
     delete:
+      description: Delete the asset criticality record for a specific asset if it exists.
       operationId: DeleteAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
@@ -45,11 +46,12 @@ paths:
                 properties:
                   deleted:
                     description: >-
-                      If the record was deleted. If false the record did not
-                      exist.
+                      True if the record was deleted or false if the record did
+                      not exist.
                     type: boolean
                   record:
                     $ref: '#/components/schemas/AssetCriticalityRecord'
+                    description: The deleted record if it existed.
                 required:
                   - deleted
           description: Successful response
@@ -59,6 +61,7 @@ paths:
       tags:
         - Security Solution Entity Analytics API
     get:
+      description: Get the criticality record for a specific asset.
       operationId: GetAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
@@ -89,6 +92,7 @@ paths:
       tags:
         - Security Solution Entity Analytics API
     post:
+      description: Create or update a criticality record for a specific asset.
       operationId: CreateAssetCriticalityRecord
       requestBody:
         content:
@@ -115,11 +119,14 @@ paths:
           description: Successful response
         '400':
           description: Invalid request
-      summary: Create Criticality Record
+      summary: Upsert Criticality Record
       tags:
         - Security Solution Entity Analytics API
   /api/asset_criticality/bulk:
     post:
+      description: >-
+        Bulk upsert up to 1000 asset criticality records, creating or updating
+        them as needed.
       operationId: BulkUpsertAssetCriticalityRecords
       requestBody:
         content:
@@ -170,13 +177,12 @@ paths:
           description: Bulk upload successful
         '413':
           description: File too large
-      summary: >-
-        Bulk upsert asset criticality data, creating or updating records as
-        needed
+      summary: Bulk Upsert Asset Criticality Records
       tags:
         - Security Solution Entity Analytics API
   /api/asset_criticality/list:
-    post:
+    get:
+      description: 'List asset criticality records, paging, sorting and filtering as needed.'
       operationId: FindAssetCriticalityRecords
       parameters:
         - description: The field to sort by.
@@ -247,7 +253,7 @@ paths:
                   - per_page
                   - total
           description: Bulk upload successful
-      summary: 'List asset criticality data, filtering and sorting as needed'
+      summary: List Asset Criticality Records
       tags:
         - Security Solution Entity Analytics API
 components:

diff --git a/x-pack/test/api_integration/services/security_solution_api.gen.ts b/x-pack/test/api_integration/services/security_solution_api.gen.ts
@@ -212,6 +212,9 @@ after 30 days. It also deletes other artifacts specific to the migration impleme
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+     * Bulk upsert up to 1000 asset criticality records, creating or updating them as needed.
+     */
     bulkUpsertAssetCriticalityRecords(props: BulkUpsertAssetCriticalityRecordsProps) {
       return supertest
         .post('/api/asset_criticality/bulk')
@@ -252,6 +255,9 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+     * Create or update a criticality record for a specific asset.
+     */
     createAssetCriticalityRecord(props: CreateAssetCriticalityRecordProps) {
       return supertest
         .post('/api/asset_criticality')
@@ -296,6 +302,9 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
+    /**
+     * Delete the asset criticality record for a specific asset if it exists.
+     */
     deleteAssetCriticalityRecord(props: DeleteAssetCriticalityRecordProps) {
       return supertest
         .delete('/api/asset_criticality')
@@ -575,9 +584,12 @@ finalize it.
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+     * List asset criticality records, paging, sorting and filtering as needed.
+     */
     findAssetCriticalityRecords(props: FindAssetCriticalityRecordsProps) {
       return supertest
-        .post('/api/asset_criticality/list')
+        .get('/api/asset_criticality/list')
         .set('kbn-xsrf', 'true')
         .set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
@@ -602,6 +614,9 @@ finalize it.
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get the criticality record for a specific asset.
+     */
     getAssetCriticalityRecord(props: GetAssetCriticalityRecordProps) {
       return supertest
         .get('/api/asset_criticality')