[Detection Engine][Docs] Added response and request descriptions for …

…API docs (#205822) # 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 Detection Engine Exception APIs.
elastic · Jan 16, 2025 · 94660cf · 94660cf
1 parent 47226c9
commit 94660cf
Show file tree

Hide file tree

Showing 40 changed files with 7,190 additions and 372 deletions.
diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
diff --git a/...docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml b/...docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml
@@ -464,11 +464,17 @@ components:
       type: object
       properties:
         _version:
+          description: >-
+            The version id, normally returned by the API when the item was
+            retrieved. Use it ensure updates are done against the latest
+            version.
           type: string
         created_at:
+          description: Autogenerated date of object creation.
           format: date-time
           type: string
         created_by:
+          description: Autogenerated value - user that created object.
           type: string
         description:
           $ref: '#/components/schemas/ExceptionListDescription'
@@ -489,13 +495,18 @@ components:
         tags:
           $ref: '#/components/schemas/ExceptionListTags'
         tie_breaker_id:
+          description: >-
+            Field used in search to ensure all containers are sorted and
+            returned correctly.
           type: string
         type:
           $ref: '#/components/schemas/ExceptionListType'
         updated_at:
+          description: Autogenerated date of last object update.
           format: date-time
           type: string
         updated_by:
+          description: Autogenerated value - user that last updated object.
           type: string
         version:
           $ref: '#/components/schemas/ExceptionListVersion'
@@ -514,31 +525,47 @@ components:
         - updated_at
         - updated_by
     ExceptionListDescription:
+      description: Describes the exception list.
+      example: This list tracks allowlisted values.
       type: string
     ExceptionListHumanId:
-      $ref: '#/components/schemas/NonEmptyString'
-      description: Human readable string identifier, e.g. `trusted-linux-processes`
+      description: >-
+        Exception list's human readable string identifier, e.g.
+        `trusted-linux-processes`.
+      example: simple_list
+      format: nonempty
+      minLength: 1
+      type: string
     ExceptionListId:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Exception list's identifier.
+      example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85
+      format: nonempty
+      minLength: 1
+      type: string
     ExceptionListItem:
       type: object
       properties:
         _version:
+          description: >-
+            The version id, normally returned by the API when the item was
+            retrieved. Use it ensure updates are done against the latest
+            version.
           type: string
         comments:
           $ref: '#/components/schemas/ExceptionListItemCommentArray'
         created_at:
+          description: Autogenerated date of object creation.
           format: date-time
           type: string
         created_by:
+          description: Autogenerated value - user that created object.
           type: string
         description:
           $ref: '#/components/schemas/ExceptionListItemDescription'
         entries:
           $ref: '#/components/schemas/ExceptionListItemEntryArray'
         expire_time:
-          format: date-time
-          type: string
+          $ref: '#/components/schemas/ExceptionListItemExpireTime'
         id:
           $ref: '#/components/schemas/ExceptionListItemId'
         item_id:
@@ -556,13 +583,18 @@ components:
         tags:
           $ref: '#/components/schemas/ExceptionListItemTags'
         tie_breaker_id:
+          description: >-
+            Field used in search to ensure all containers are sorted and
+            returned correctly.
           type: string
         type:
           $ref: '#/components/schemas/ExceptionListItemType'
         updated_at:
+          description: Autogenerated date of last object update.
           format: date-time
           type: string
         updated_by:
+          description: Autogenerated value - user that last updated object.
           type: string
       required:
         - id
@@ -585,13 +617,15 @@ components:
         comment:
           $ref: '#/components/schemas/NonEmptyString'
         created_at:
+          description: Autogenerated date of object creation.
           format: date-time
           type: string
         created_by:
           $ref: '#/components/schemas/NonEmptyString'
         id:
           $ref: '#/components/schemas/NonEmptyString'
         updated_at:
+          description: Autogenerated date of last object update.
           format: date-time
           type: string
         updated_by:
@@ -602,10 +636,15 @@ components:
         - created_at
         - created_by
     ExceptionListItemCommentArray:
+      description: |
+        Array of comment fields:
+
+        - comment (string): Comments about the exception item.
       items:
         $ref: '#/components/schemas/ExceptionListItemComment'
       type: array
     ExceptionListItemDescription:
+      description: Describes the exception list.
       type: string
     ExceptionListItemEntry:
       anyOf:
@@ -747,47 +786,80 @@ components:
         - excluded
         - included
       type: string
+    ExceptionListItemExpireTime:
+      description: >-
+        The exception item’s expiration date, in ISO format. This field is only
+        available for regular exception items, not endpoint exceptions.
+      format: date-time
+      type: string
     ExceptionListItemHumanId:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Human readable string identifier, e.g. `trusted-linux-processes`
+      example: simple_list_item
+      format: nonempty
+      minLength: 1
+      type: string
     ExceptionListItemId:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Exception's identifier.
+      example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2
+      format: nonempty
+      minLength: 1
+      type: string
     ExceptionListItemMeta:
       additionalProperties: true
       type: object
     ExceptionListItemName:
-      $ref: '#/components/schemas/NonEmptyString'
+      description: Exception list name.
+      format: nonempty
+      minLength: 1
+      type: string
     ExceptionListItemOsTypeArray:
       items:
         $ref: '#/components/schemas/ExceptionListOsType'
       type: array
     ExceptionListItemTags:
       items:
-        $ref: '#/components/schemas/NonEmptyString'
+        description: >-
+          String array containing words and phrases to help categorize exception
+          items.
+        format: nonempty
+        minLength: 1
+        type: string
       type: array
     ExceptionListItemType:
       enum:
         - simple
       type: string
     ExceptionListMeta:
       additionalProperties: true
+      description: Placeholder for metadata about the list container.
       type: object
     ExceptionListName:
+      description: The name of the exception list.
+      example: My exception list
       type: string
     ExceptionListOsType:
+      description: Use this field to specify the operating system.
       enum:
         - linux
         - macos
         - windows
       type: string
     ExceptionListOsTypeArray:
+      description: Use this field to specify the operating system. Only enter one value.
       items:
         $ref: '#/components/schemas/ExceptionListOsType'
       type: array
     ExceptionListTags:
+      description: >-
+        String array containing words and phrases to help categorize exception
+        containers.
       items:
         type: string
       type: array
     ExceptionListType:
+      description: >-
+        The type of exception list to be created. Different list types may
+        denote where they can be utilized.
       enum:
         - detection
         - rule_default
@@ -798,6 +870,7 @@ components:
         - endpoint_blocklists
       type: string
     ExceptionListVersion:
+      description: The document version, automatically increasd on updates.
       minimum: 1
       type: integer
     ExceptionNamespaceType: