Added examples for necessary Entity Analytics OpenAPI docs (elastic#2…

…05439) As part of the effort to add missing content for Security APIs, this PR introduces a few missing request, response, and parameter examples for Security Entity Analytics APIs. All of the affected APIs are the Asset Criticality APIs. Until the docs are deployed, this can be tested by navigating to https://editor.swagger.io/ and pasting in the fully bundled file, which can be found [here](https://github.com/elastic/kibana/blob/f905638686cc242416c1d9adf0595c9f56cbc12d/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml) in the PR --------- Co-authored-by: kibanamachine <[email protected]> Co-authored-by: Elastic Machine <[email protected]> (cherry picked from commit f2c0ee8)
hop-dev · Jan 24, 2025 · 7075575 · 7075575
1 parent cb94251
commit 7075575
Show file tree

Hide file tree

Showing 8 changed files with 172 additions and 4 deletions.
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
@@ -6118,6 +6118,7 @@ paths:
       operationId: DeleteAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -6164,6 +6165,7 @@ paths:
       operationId: GetAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -6209,6 +6211,10 @@ paths:
                       enum:
                         - wait_for
                       type: string
+              example:
+                criticality_level: high_impact
+                id_field: host.name
+                id_value: my_host
         required: true
       responses:
         '200':
@@ -6332,6 +6338,31 @@ paths:
           content:
             application/json; Elastic-Api-Version=2023-10-31:
               schema:
+                example:
+                  page: 1
+                  per_page: 10
+                  records:
+                    - '@timestamp': '2024-08-02T14:40:35.705Z'
+                      asset:
+                        criticality: medium_impact
+                      criticality_level: medium_impact
+                      host:
+                        asset:
+                          criticality: medium_impact
+                        name: my_other_host
+                      id_field: host.name
+                      id_value: my_other_host
+                    - '@timestamp': '2024-08-02T11:15:34.290Z'
+                      asset:
+                        criticality: high_impact
+                      criticality_level: high_impact
+                      host:
+                        asset:
+                          criticality: high_impact
+                        name: my_host
+                      id_field: host.name
+                      id_value: my_host
+                  total: 2
                 type: object
                 properties:
                   page:
@@ -6353,7 +6384,7 @@ paths:
                   - page
                   - per_page
                   - total
-          description: Bulk upload successful
+          description: Successfully retrieved asset criticality records
       summary: List asset criticality records
       tags:
         - Security Entity Analytics API
@@ -38100,6 +38131,17 @@ components:
               type: string
           required:
             - '@timestamp'
+      example:
+        '@timestamp': '2024-08-02T11:15:34.290Z'
+        asset:
+          criticality: high_impact
+        criticality_level: high_impact
+        host:
+          asset:
+            criticality: high_impact
+          name: my_host
+        id_field: host.name
+        id_value: my_host
     Security_Entity_Analytics_API_AssetCriticalityRecordEcsParts:
       type: object
       properties:

diff --git a/...lugins/security_solution/common/api/entity_analytics/asset_criticality/common.schema.yaml b/...lugins/security_solution/common/api/entity_analytics/asset_criticality/common.schema.yaml
@@ -59,6 +59,17 @@ components:
           required:
             - criticality_level
     AssetCriticalityRecord:
+      example:
+        id_field: 'host.name'
+        id_value: my_host
+        criticality_level: high_impact
+        '@timestamp': '2024-08-02T11:15:34.290Z'
+        asset:
+          criticality: high_impact
+        host:
+          name: my_host
+          asset:
+            criticality: high_impact
       allOf:
         - $ref: '#/components/schemas/CreateAssetCriticalityRecord'
         - $ref: '#/components/schemas/AssetCriticalityRecordEcsParts'

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
@@ -19,6 +19,10 @@ paths:
         content:
           application/json:
             schema:
+              example:
+                id_field: 'host.name'
+                id_value: 'my_host'
+                criticality_level: 'high_impact'
               allOf:
                 - $ref: './common.schema.yaml#/components/schemas/CreateAssetCriticalityRecord'
                 - type: object

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
@@ -17,6 +17,7 @@ paths:
           required: true
           schema:
             type: string
+          example: my_host
           description: The ID value of the asset.
         - name: id_field
           in: query

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
@@ -17,6 +17,7 @@ paths:
           required: true
           schema:
             type: string
+          example: 'my_host'
           description: The ID value of the asset.
         - name: id_field
           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
@@ -55,11 +55,36 @@ paths:
           description: The kuery to filter by.
       responses:
         '200':
-          description: Bulk upload successful
+          description: Successfully retrieved asset criticality records
           content:
             application/json:
               schema:
                 type: object
+                example:
+                  records:
+                    - id_field: 'host.name'
+                      id_value: 'my_other_host'
+                      criticality_level: 'medium_impact'
+                      '@timestamp': '2024-08-02T14:40:35.705Z'
+                      asset:
+                        criticality: medium_impact
+                      host:
+                        name: my_other_host
+                        asset:
+                          criticality: medium_impact
+                    - id_field: 'host.name'
+                      id_value: 'my_host'
+                      criticality_level: 'high_impact'
+                      '@timestamp': '2024-08-02T11:15:34.290Z'
+                      asset:
+                        criticality: high_impact
+                      host:
+                        name: my_host
+                        asset:
+                          criticality: high_impact
+                  total: 2
+                  page: 1
+                  per_page: 10
                 properties:
                   records:
                     type: array

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
@@ -17,6 +17,7 @@ paths:
       operationId: DeleteAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -65,6 +66,7 @@ paths:
       operationId: GetAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -115,6 +117,10 @@ paths:
                       enum:
                         - wait_for
                       type: string
+              example:
+                criticality_level: high_impact
+                id_field: host.name
+                id_value: my_host
         required: true
       responses:
         '200':
@@ -242,6 +248,31 @@ paths:
           content:
             application/json:
               schema:
+                example:
+                  page: 1
+                  per_page: 10
+                  records:
+                    - '@timestamp': '2024-08-02T14:40:35.705Z'
+                      asset:
+                        criticality: medium_impact
+                      criticality_level: medium_impact
+                      host:
+                        asset:
+                          criticality: medium_impact
+                        name: my_other_host
+                      id_field: host.name
+                      id_value: my_other_host
+                    - '@timestamp': '2024-08-02T11:15:34.290Z'
+                      asset:
+                        criticality: high_impact
+                      criticality_level: high_impact
+                      host:
+                        asset:
+                          criticality: high_impact
+                        name: my_host
+                      id_field: host.name
+                      id_value: my_host
+                  total: 2
                 type: object
                 properties:
                   page:
@@ -263,7 +294,7 @@ paths:
                   - page
                   - per_page
                   - total
-          description: Bulk upload successful
+          description: Successfully retrieved asset criticality records
       summary: List asset criticality records
       tags:
         - Security Entity Analytics API
@@ -685,6 +716,17 @@ components:
               type: string
           required:
             - '@timestamp'
+      example:
+        '@timestamp': '2024-08-02T11:15:34.290Z'
+        asset:
+          criticality: high_impact
+        criticality_level: high_impact
+        host:
+          asset:
+            criticality: high_impact
+          name: my_host
+        id_field: host.name
+        id_value: my_host
     AssetCriticalityRecordEcsParts:
       type: object
       properties:

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
@@ -17,6 +17,7 @@ paths:
       operationId: DeleteAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -65,6 +66,7 @@ paths:
       operationId: GetAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -115,6 +117,10 @@ paths:
                       enum:
                         - wait_for
                       type: string
+              example:
+                criticality_level: high_impact
+                id_field: host.name
+                id_value: my_host
         required: true
       responses:
         '200':
@@ -242,6 +248,31 @@ paths:
           content:
             application/json:
               schema:
+                example:
+                  page: 1
+                  per_page: 10
+                  records:
+                    - '@timestamp': '2024-08-02T14:40:35.705Z'
+                      asset:
+                        criticality: medium_impact
+                      criticality_level: medium_impact
+                      host:
+                        asset:
+                          criticality: medium_impact
+                        name: my_other_host
+                      id_field: host.name
+                      id_value: my_other_host
+                    - '@timestamp': '2024-08-02T11:15:34.290Z'
+                      asset:
+                        criticality: high_impact
+                      criticality_level: high_impact
+                      host:
+                        asset:
+                          criticality: high_impact
+                        name: my_host
+                      id_field: host.name
+                      id_value: my_host
+                  total: 2
                 type: object
                 properties:
                   page:
@@ -263,7 +294,7 @@ paths:
                   - page
                   - per_page
                   - total
-          description: Bulk upload successful
+          description: Successfully retrieved asset criticality records
       summary: List asset criticality records
       tags:
         - Security Entity Analytics API
@@ -685,6 +716,17 @@ components:
               type: string
           required:
             - '@timestamp'
+      example:
+        '@timestamp': '2024-08-02T11:15:34.290Z'
+        asset:
+          criticality: high_impact
+        criticality_level: high_impact
+        host:
+          asset:
+            criticality: high_impact
+          name: my_host
+        id_field: host.name
+        id_value: my_host
     AssetCriticalityRecordEcsParts:
       type: object
       properties: