[Security] Timeline OpenAPI documentation fixes (#186458)

## Summary

- Fix issues that came up during validation with `spectral lint` running
with the [recommended
settings](https://docs.elastic.dev/content-architecture/oas#openapi-version).
- Made sure all return and request types match with the code
- Fixed incorrect descriptions and links to documenation

Fixes https://github.com/elastic/kibana/issues/183812.

---------

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

x-pack/plugins/security_solution/common/api/timeline/clean_draft_timelines/clean_draft_timelines_route_schema.yaml

@@ -29,7 +29,7 @@ paths:
                 timelineType:
                   $ref: '../model/components.yaml#/components/schemas/TimelineType'
       responses:
-        200:
+        '200':
           description: Indicates that the draft timeline was successfully created. In the event the user already has a draft timeline, the existing draft timeline is cleared and returned.
           content:
             application/json:
@@ -46,7 +46,7 @@ paths:
                             $ref: '../model/components.yaml#/components/schemas/TimelineResponse'
                 required:
                   - data
-        403:
+        '403':
           description: Indicates that the user does not have the required permissions to create a draft timeline.
           content:
             application:json:
@@ -57,7 +57,7 @@ paths:
                     type: string
                   status_code:
                     type: number
-        409:
+        '409':
           description: Indicates that there is already a draft timeline with the given timelineId.
           content:
             application:json:

x-pack/plugins/security_solution/common/api/timeline/create_timelines/create_timelines_route_schema.yaml

@@ -16,7 +16,7 @@ paths:
   /api/timeline:
     post:
       operationId: createTimelines
-      description: Creates a new timeline.
+      summary: Creates a new timeline.
       tags:
         - access:securitySolution
       requestBody:
@@ -52,7 +52,7 @@ paths:
                 timeline:
                   $ref: '../model/components.yaml#/components/schemas/SavedTimeline'
       responses:
-        200:
+        '200':
           description: Indicates the timeline was successfully created.
           content:
             application/json:
@@ -69,7 +69,7 @@ paths:
                             $ref: '../model/components.yaml#/components/schemas/TimelineResponse'
                 required:
                   - data
-        405:
+        '405':
           description: Indicates that there was an error in the timeline creation.
           content:
             application/json:

x-pack/plugins/security_solution/common/api/timeline/delete_note/delete_note_route_schema.yaml

@@ -13,7 +13,7 @@ paths:
   /api/note:
     delete:
       operationId: deleteNote
-      description: Deletes a note from a timeline.
+      summary: Deletes a note from a timeline.
       tags:
         - access:securitySolution
       requestBody:
@@ -36,5 +36,12 @@ paths:
                     type: string
                     nullable: true
       responses:
-        200:
-          description: Indicates the note was successfully deleted.
+        '200':
+          description: Indicates the note was successfully deleted.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: object

x-pack/plugins/security_solution/common/api/timeline/delete_timelines/delete_timelines_route_schema.yaml

@@ -16,7 +16,7 @@ paths:
   /api/timeline:
     delete:
       operationId: deleteTimelines
-      description: Deletes one or more timelines or timeline templates.
+      summary: Deletes one or more timelines or timeline templates.
       tags:
         - access:securitySolution
       requestBody:
@@ -33,12 +33,13 @@ paths:
                   type: array
                   items:
                     type: string
-                searchId:
+                searchIds:
                   type: array
+                  description: Saved search ids that should be deleted alongside the timelines 
                   items:
                     type: string
       responses:
-        200:
+        '200':
           description: Indicates the timeline was successfully deleted.
           content:
             application/json:

x-pack/plugins/security_solution/common/api/timeline/export_timelines/export_timelines_route_schema.yaml

@@ -16,7 +16,7 @@ paths:
   /api/timeline/_export:
     post:
       operationId: exportTimelines
-      description: Exports timelines as an NDJSON file
+      summary: Exports timelines as an NDJSON file
       tags:
         - access:securitySolution
       parameters:
@@ -26,7 +26,7 @@ paths:
             type: string
           description: The name of the file to export
       requestBody:
-        description: The id of the timelines to export
+        description: The ids of the timelines to export
         required: true
         content:
           application/json:
@@ -39,14 +39,14 @@ paths:
                   items:
                     type: string
       responses:
-        200:
+        '200':
           description: Indicates the timelines were successfully exported
           content:
             application/ndjson:
               schema:
                 type: string
                 description: NDJSON of the exported timelines
-        400:
+        '400':
           description: Indicates that the export size limit was exceeded
           content:
             application/ndjson:

x-pack/plugins/security_solution/common/api/timeline/get_draft_timelines/get_draft_timelines_route_schema.yaml

@@ -2,9 +2,6 @@ openapi: 3.0.0
 info:
   title: Elastic Security - Timeline - Get Draft Timelines API
   version: 8.9.0
-externalDocs:
-  url: https://www.elastic.co/guide/en/security/current/_get_timeline_timeline_template_by_savedobjectid.html
-  description: Documentation
 servers:
   - url: 'http://{kibana_host}:{port}'
     variables:
@@ -16,7 +13,7 @@ paths:
   /api/timeline/_draft:
     get:
       operationId: getDraftTimelines
-      description: Retrieves the draft timeline for the current user. If the user does not have a draft timeline, an empty timeline is returned.
+      summary: Retrieves the draft timeline for the current user. If the user does not have a draft timeline, an empty timeline is returned.
       tags:
         - access:securitySolution
       parameters:
@@ -25,7 +22,7 @@ paths:
           schema:
             $ref: '../model/components.yaml#/components/schemas/TimelineType'
       responses:
-        200:
+        '200':
           description: Indicates that the draft timeline was successfully retrieved.
           content:
             application/json:
@@ -40,7 +37,7 @@ paths:
                         properties:
                           timeline:
                             $ref: '../model/components.yaml#/components/schemas/TimelineResponse'
-        403:
+        '403':
           description: If a draft timeline was not found and we attempted to create one, it indicates that the user does not have the required permissions to create a draft timeline.
           content:
             application:json:
@@ -51,7 +48,7 @@ paths:
                     type: string
                   status_code:
                     type: number
-        409:
+        '409':
           description: This should never happen, but if a draft timeline was not found and we attempted to create one, it indicates that there is already a draft timeline with the given timelineId.
           content:
             application:json:

x-pack/plugins/security_solution/common/api/timeline/get_timeline/get_timeline_route_schema.yaml

@@ -3,7 +3,7 @@ info:
   title: Elastic Security - Timeline - Get Timeline API
   version: 8.9.0
 externalDocs:
-  url: https://www.elastic.co/guide/en/security/current/_get_timeline_timeline_template_by_savedobjectid.html
+  url: https://www.elastic.co/guide/en/security/current/_get_timeline_or_timeline_template_by_savedobjectid.html
   description: Documentation
 servers:
   - url: 'http://{kibana_host}:{port}'
@@ -16,7 +16,7 @@ paths:
   /api/timeline:
     get:
       operationId: getTimeline
-      description: Get an existing saved timeline or timeline template. This API is used to retrieve an existing saved timeline or timeline template.
+      summary: Get an existing saved timeline or timeline template. This API is used to retrieve an existing saved timeline or timeline template.
       tags:
         - access:securitySolution
       parameters:
@@ -31,8 +31,8 @@ paths:
             type: string
           description: The ID of the timeline to retrieve
       responses:
-        200:
-          description: Indicates that the draft timeline was successfully created. In the event the user already has a draft timeline, the existing draft timeline is cleared and returned.
+        '200':
+          description: Indicates that the (template) timeline was found and returned.
           content:
             application/json:
               schema:

x-pack/plugins/security_solution/common/api/timeline/get_timelines/get_timelines_route_schema.yaml

@@ -16,7 +16,7 @@ paths:
   /api/timelines:
     get:
       operationId: getTimelines
-      description: This API is used to retrieve a list of existing saved timelines or timeline templates.
+      summary: This API is used to retrieve a list of existing saved timelines or timeline templates.
       tags:
         - access:securitySolution
       parameters:
@@ -68,8 +68,8 @@ paths:
              - $ref: '../model/components.yaml#/components/schemas/TimelineStatus'
              - nullable: true
       responses:
-        200:
-          description: Indicates that the draft timeline was successfully created. In the event the user already has a draft timeline, the existing draft timeline is cleared and returned.
+        '200':
+          description: Indicates that the (template) timelines were found and returned.
           content:
             application/json:
               schema:
@@ -96,7 +96,7 @@ paths:
                         type: number
                 required:
                   - data
-        400:
+        '400':
           description: Bad request. The user supplied invalid data.
           content:
             application:json:

x-pack/plugins/security_solution/common/api/timeline/import_timelines/import_timelines_route_schema.yaml

@@ -16,7 +16,7 @@ paths:
   /api/timeline/_import:
     post:
       operationId: importTimelines
-      description: Imports timelines.
+      summary: Imports timelines.
       tags:
         - access:securitySolution
       requestBody:
@@ -40,7 +40,7 @@ paths:
                           headers:
                             type: object
       responses:
-        200:
+        '200':
           description: Indicates the import of timelines was successful.
           content:
             application/json:
@@ -52,7 +52,7 @@ paths:
                 required:
                   - data
 
-        400:
+        '400':
           description: Indicates the import of timelines was unsuccessful because of an invalid file extension.
           content:
             application/json:
@@ -66,7 +66,7 @@ paths:
                   statusCode:
                     type: number
 
-        404:
+        '404':
           description: Indicates that we were unable to locate the saved object client necessary to handle the import.
           content:
             application/json:
@@ -77,7 +77,7 @@ paths:
                     type: string
                   statusCode:
                     type: number
-        409:
+        '409':
           description: Indicates the import of timelines was unsuccessful.
           content:
             application/json:

x-pack/plugins/security_solution/common/api/timeline/install_prepackaged_timelines/install_prepackaged_timelines_route_schema.yaml

@@ -13,7 +13,7 @@ paths:
   /api/timeline/_prepackaged:
     post:
       operationId: installPrepackedTimelines
-      description: Installs prepackaged timelines.
+      summary: Installs prepackaged timelines.
       tags:
         - access:securitySolution
       requestBody:
@@ -41,7 +41,7 @@ paths:
                   items:
                     $ref: '../model/components.yaml#/components/schemas/SavedTimeline'
       responses:
-        200:
+        '200':
           description: Indicates the installation of prepackaged timelines was successful.
           content:
             application/json:
@@ -52,7 +52,7 @@ paths:
                     $ref: '../model/components.yaml#/components/schemas/ImportTimelineResult'
                 required:
                   - data
-        500:
+        '500':
           description: Indicates the installation of prepackaged timelines was unsuccessful.
           content:
             application:json:

x-pack/plugins/security_solution/common/api/timeline/patch_timelines/patch_timeline_route_schema.yaml

@@ -32,7 +32,7 @@ paths:
                 timeline:
                   $ref: '../model/components.yaml#/components/schemas/SavedTimeline'
       responses:
-        200:
+        '200':
           description: Indicates that the draft timeline was successfully created. In the event the user already has a draft timeline, the existing draft timeline is cleared and returned.
           content:
             application/json:
@@ -49,7 +49,7 @@ paths:
                             $ref: '../model/components.yaml#/components/schemas/TimelineResponse'
                 required:
                   - data
-        405:
+        '405':
           description: Indicates that the user does not have the required access to create a draft timeline.
           content:
             application/json:

x-pack/plugins/security_solution/common/api/timeline/persist_favorite/persist_favorite_route_schema.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.0
 info:
-  title: Elastic Security - Timeline - Favorite API (https://www.elastic.co/guide/en/security/current/timeline-api-delete.html)
+  title: Elastic Security - Timeline - Favorite API
   version: 8.9.0
 servers:
   - url: 'http://{kibana_host}:{port}'
@@ -13,11 +13,11 @@ paths:
   /api/timeline/_favorite:
     patch:
       operationId: persistFavoriteRoute
-      description: Persists a given users favorite status of a timeline.
+      summary: Persists a given users favorite status of a timeline.
       tags:
         - access:securitySolution
       requestBody:
-        description: The required timeline fields used to create a new timeline along with optional fields that will be created if not provided.
+        description: The required fields used to favorite a (template) timeline.
         required: true
         content:
           application/json:
@@ -38,7 +38,7 @@ paths:
                     - $ref: '../model/components.yaml#/components/schemas/TimelineType'
                     - nullable: true
       responses:
-        200:
+        '200':
           description: Indicates the favorite status was successfully updated.
           content:
             application/json:
@@ -52,7 +52,7 @@ paths:
                         $ref: '../model/components.yaml#/components/schemas/FavoriteTimelineResponse'
                 required:
                   - data
-        403:
+        '403':
           description: Indicates the user does not have the required permissions to persist the favorite status.
           content:
             application:json:

x-pack/plugins/security_solution/common/api/timeline/persist_note/persist_note_route_schema.yaml

@@ -15,8 +15,8 @@ servers:
 paths:
   /api/note:
     patch:
-      operationId: persistNoteroute
-      description: Persists a note to a timeline.
+      operationId: persistNoteRoute
+      summary: Persists a note to a timeline.
       tags:
         - access:securitySolution
       requestBody:
@@ -41,8 +41,8 @@ paths:
                   type: string
                   nullable: true
       responses:
-        200:
-          description: Indicates the favorite status was successfully updated.
+        '200':
+          description: Indicates the note was successfully created.
           content:
             application/json:
               schema:

x-pack/plugins/security_solution/common/api/timeline/pinned_events/pinned_events_route_schema.yaml

@@ -1,7 +1,10 @@
 openapi: 3.0.0
 info:
-  title: Elastic Security - Timeline - Pinned Event API (https://www.elastic.co/guide/en/security/current/_pin_an_event_to_an_existing_timeline.html)
+  title: Elastic Security - Timeline - Pinned Event API
   version: 8.14.0
+externalDocs:
+  url: https://www.elastic.co/guide/en/security/current/_pin_an_event_to_an_existing_timeline.html
+  description: Documentation
 servers:
   - url: 'http://{kibana_host}:{port}'
     variables:
@@ -13,7 +16,7 @@ paths:
   /api/pinned_event:
     patch:
       operationId: persistPinnedEventRoute
-      description: Persists a pinned event to a timeline.
+      summary: Persists a pinned event to a timeline.
       tags:
         - access:securitySolution
       requestBody:
@@ -34,7 +37,7 @@ paths:
                 timelineId:
                   type: string
       responses:
-        200:
+        '200':
           description: Indicate the event was successfully pinned in the timeline.
           content:
             application/json:

x-pack/plugins/security_solution/server/lib/timeline/routes/notes/delete_note.ts

@@ -48,22 +48,22 @@ export const deleteNoteRoute = (
           const noteId = request.body?.noteId ?? '';
           const noteIds = request.body?.noteIds ?? null;
           if (noteIds != null) {
-            const res = await deleteNote({
+            await deleteNote({
               request: frameworkRequest,
               noteIds,
             });
 
             return response.ok({
-              body: { data: { persistNote: res } },
+              body: { data: {} },
             });
           } else {
-            const res = await deleteNote({
+            await deleteNote({
               request: frameworkRequest,
               noteIds: [noteId],
             });
 
             return response.ok({
-              body: { data: { persistNote: res } },
+              body: { data: {} },
             });
           }
         } catch (err) {