Adds OpenAPI specs for case comment endpoints (#133400) (#134556)

Co-authored-by: Lisa Cawley <[email protected]> (cherry picked from commit b05f8c1) Co-authored-by: István Zoltán Szabó <[email protected]>
elastic · Jun 16, 2022 · ba70bdf · ba70bdf
1 parent bb660ed
commit ba70bdf
Show file tree

Hide file tree

Showing 24 changed files with 6,078 additions and 1,853 deletions.
diff --git a/docs/api/cases/cases-api-add-comment.asciidoc b/docs/api/cases/cases-api-add-comment.asciidoc
@@ -4,7 +4,7 @@
 <titleabbrev>Add comment</titleabbrev>
 ++++
 
-Adds a comment to a case.
+Adds a comment or alert to a case.
 
 === {api-request-title}
 
@@ -78,7 +78,7 @@ Add a comment to case ID `293f1bc0-74f6-11ea-b83a-553aecdb28b6`:
 POST api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments
 {
   "type": "user",
-  "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.",
+  "comment": "A new comment.",
   "owner": "cases"
 }
 --------------------------------------------------
@@ -93,30 +93,30 @@ The API returns details about the case and its comments. For example:
     {
       "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
       "version": "WzIwNDMxLDFd",
-      "type":"user",
-      "owner":"cases",
-      "comment":"That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.",
-      "created_at":"2022-03-24T00:49:47.716Z",
+      "type": "user",
+      "owner": "cases",
+      "comment": "A new comment.",
+      "created_at": "2022-03-24T00:49:47.716Z",
       "created_by": {
-        "email": "[email protected]",
-        "full_name": "Ms Moneypenny",
-        "username": "moneypenny"
+        "email": null,
+        "full_name": null,
+        "username": "elastic"
       },
-      "pushed_at":null,
-      "pushed_by":null,
-      "updated_at":null,
-      "updated_by":null
+      "pushed_at": null,
+      "pushed_by": null,
+      "updated_at": null,
+      "updated_by": null
     }
   ],
-  "totalAlerts":0,
-  "id":"293f1bc0-74f6-11ea-b83a-553aecdb28b6",
-  "version":"WzIzMzgsMV0=",
-  "totalComment":1,
-  "title": "This case will self-destruct in 5 seconds",
-  "tags": ["phishing","social engineering"],
-  "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
+  "totalAlerts": 0,
+  "id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
+  "version": "WzIzMzgsMV0=",
+  "totalComment": 1,
+  "title": "Case title 1",
+  "tags": ["tag 1"],
+  "description": "A case description.",
   "settings": {
-    "syncAlerts":false
+    "syncAlerts": false
   },
   "owner": "cases",
   "duration": null,
@@ -125,16 +125,16 @@ The API returns details about the case and its comments. For example:
   "closed_by": null,
   "created_at": "2022-03-24T00:37:03.906Z",
   "created_by": {
-    "email": "[email protected]",
-    "full_name": "Alan Hunley",
-    "username": "ahunley"
+    "email": null,
+    "full_name": null,
+    "username": "elastic"
   },
   "status": "open",
   "updated_at": "2022-03-24T00:49:47.716Z",
   "updated_by": {
-    "email": "[email protected]",
-    "full_name": "Ms Moneypenny",
-    "username": "moneypenny"
+    "email": null,
+    "full_name": null,
+    "username": "elastic"
   },
   "connector": {
     "id": "none",
@@ -152,13 +152,13 @@ Add an alert to the case:
 --------------------------------------------------
 POST api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments
 {
-"alertId": "6b24c4dc44bc720cfc92797f3d61fff952f2b2627db1fb4f8cc49f4530c4ff42",
-"index": ".internal.alerts-security.alerts-default-000001",
-"type": "alert",
-"owner": "cases",
-"rule": {
-  "id":"94d80550-aaf4-11ec-985f-97e55adae8b9",
-  "name":"security_rule"
+  "alertId": "6b24c4dc44bc720cfc92797f3d61fff952f2b2627db1fb4f8cc49f4530c4ff42",
+  "index": ".internal.alerts-security.alerts-default-000001",
+  "type": "alert",
+  "owner": "cases",
+  "rule": {
+    "id":"94d80550-aaf4-11ec-985f-97e55adae8b9",
+    "name":"security_rule"
   }
 }
 --------------------------------------------------

diff --git a/docs/api/cases/cases-api-delete-comments.asciidoc b/docs/api/cases/cases-api-delete-comments.asciidoc
@@ -4,7 +4,7 @@
 <titleabbrev>Delete comments</titleabbrev>
 ++++
 
-Deletes one or all comments from a case.
+Deletes one or all comments and alerts from a case.
 
 === {api-request-title}
 

diff --git a/docs/api/cases/cases-api-update-comment.asciidoc b/docs/api/cases/cases-api-update-comment.asciidoc
@@ -4,7 +4,7 @@
 <titleabbrev>Update comment</titleabbrev>
 ++++
 
-Updates a comment in a case.
+Updates a comment or alert in a case.
 
 === {api-request-title}
 
@@ -40,7 +40,8 @@ default space is used.
 `user`.
 
 `id`::
-(Required, string) The identifier for the comment. To retrieve comment IDs, use <<cases-api-get-comments>>.
+(Required, string) The identifier for the comment. To retrieve comment IDs, use
+<<cases-api-get-comments>>.
 
 `index`::
 (Required*, string) The alert index. It is required only when `type` is `alert`.
@@ -74,7 +75,8 @@ The rule that is associated with the alert. It is required only when `type` is
 NOTE: You cannot change the comment type.
 
 `version`::
-(Required, string) The current comment version. To retrieve version values, use <<cases-api-get-comments>>.
+(Required, string) The current comment version. To retrieve version values, use
+<<cases-api-get-comments>>.
 
 === {api-response-codes-title}
 
@@ -93,7 +95,7 @@ PATCH api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments
   "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
   "version": "Wzk1LDFd",
   "type": "user",
-  "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives. Even worse, he likes baked beans."
+  "comment": "An updated comment."
 }
 --------------------------------------------------
 // KIBANA
@@ -106,32 +108,32 @@ The API returns details about the case and its comments. For example:
   "comments":[{
     "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
     "version": "WzIwNjM3LDFd",
-    "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives. Even worse, he likes baked beans.",
+    "comment": "An updated comment.",
     "type": "user",
     "owner": "cases",
     "created_at": "2022-03-24T00:37:10.832Z",
     "created_by": {
-        "email": "[email protected]",
-        "full_name": "Ms Moneypenny",
-        "username": "moneypenny"
+        "email": null,
+        "full_name": null,
+        "username": "elastic"
     },
     "pushed_at": null,
     "pushed_by": null,
     "updated_at": "2022-03-24T01:27:06.210Z",
     "updated_by": {
-        "email": "[email protected]",
-        "full_name": "James Bond",
-        "username": "_007"
+        "email": null,
+        "full_name": null,
+        "username": "elastic"
       }
     }
   ],
   "totalAlerts": 0,
   "id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
   "version": "WzIwNjM2LDFd",
   "totalComment": 1,
-  "title": "This case will self-destruct in 5 seconds",
-  "tags": ["phishing","social engineering"],
-  "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
+  "title": "Case title 1",
+  "tags": ["tag 1"],
+  "description": "A case description.",
   "settings": {"syncAlerts":false},
   "owner": "cases",
   "duration": null,
@@ -140,18 +142,23 @@ The API returns details about the case and its comments. For example:
   "closed_by": null,
   "created_at": "2022-03-24T00:37:03.906Z",
   "created_by": {
-    "email": "[email protected]",
-    "full_name": "Alan Hunley",
-    "username": "ahunley"
+    "email": null,
+    "full_name": null,
+    "username": "elastic"
   },
   "status": "open",
   "updated_at": "2022-03-24T01:27:06.210Z",
   "updated_by": {
-    "email": "[email protected]",
-    "full_name": "James Bond",
-    "username": "_007"
+    "email": null,
+    "full_name": null,
+    "username": "elastic"
+  },
+  "connector": {
+    "id": "none",
+    "name": "none",
+    "type": ".none",
+    "fields": null
   },
-  "connector": {"id":"none","name":"none","type":".none","fields":null},
   "external_service": null
 }
 --------------------------------------------------
@@ -162,16 +169,16 @@ Update an alert in the case:
 --------------------------------------------------
 PATCH api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments
 {
-"id": "73362370-ab1a-11ec-985f-97e55adae8b9",
-"version": "WzMwNDgsMV0=",
-"type": "alert",
-"owner": "cases",
-"alertId": "c8789278659fdf88b7bf7709b90a082be070d0ba4c23c9c4b552e476c2a667c4",
-"index": ".internal.alerts-security.alerts-default-000001",
-"rule":
-{
-  "id":"94d80550-aaf4-11ec-985f-97e55adae8b9",
-  "name":"security_rule"
+  "id": "73362370-ab1a-11ec-985f-97e55adae8b9",
+  "version": "WzMwNDgsMV0=",
+  "type": "alert",
+  "owner": "cases",
+  "alertId": "c8789278659fdf88b7bf7709b90a082be070d0ba4c23c9c4b552e476c2a667c4",
+  "index": ".internal.alerts-security.alerts-default-000001",
+  "rule":
+  {
+    "id":"94d80550-aaf4-11ec-985f-97e55adae8b9",
+    "name":"security_rule"
   }
 }
 --------------------------------------------------