Added examples for necessary Entity Analytics OpenAPI docs (#205439)

# Summary 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. # How to Test 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]>
elastic · Jan 15, 2025 · f2c0ee8 · f2c0ee8
1 parent 4c6abde
commit f2c0ee8
Show file tree

Hide file tree

Showing 9 changed files with 215 additions and 5 deletions.
diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml
@@ -4862,6 +4862,7 @@ paths:
       operationId: DeleteAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -4909,6 +4910,7 @@ paths:
       operationId: GetAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -4955,6 +4957,10 @@ paths:
                       enum:
                         - wait_for
                       type: string
+              example:
+                criticality_level: high_impact
+                id_field: host.name
+                id_value: my_host
         required: true
       responses:
         '200':
@@ -5080,6 +5086,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:
@@ -5101,7 +5132,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
@@ -47126,6 +47157,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/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
@@ -5190,6 +5190,7 @@ paths:
       operationId: DeleteAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -5236,6 +5237,7 @@ paths:
       operationId: GetAssetCriticalityRecord
       parameters:
         - description: The ID value of the asset.
+          example: my_host
           in: query
           name: id_value
           required: true
@@ -5281,6 +5283,10 @@ paths:
                       enum:
                         - wait_for
                       type: string
+              example:
+                criticality_level: high_impact
+                id_field: host.name
+                id_value: my_host
         required: true
       responses:
         '200':
@@ -5404,6 +5410,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:
@@ -5425,7 +5456,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
@@ -54001,6 +54032,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
@@ -61,6 +61,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
@@ -776,6 +807,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: