[8.x] Improves Timeline API docs content (elastic#192744) (elastic#20…

…4900)

# Backport

This will backport the following commits from `main` to `8.x`:
- [Improves Timeline API docs content
(elastic#192744)](elastic#192744)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT
[{"author":{"name":"natasha-moore-elastic","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-09-19T08:03:59Z","message":"Improves
Timeline API docs content (elastic#192744)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#35
by\r\nimproving the Timeline API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
Jatin Kathuria <[email protected]>\r\nCo-authored-by: kibanamachine
<[email protected]>","sha":"9765f73ec2ab4d1ef2406247503b1ceaba1c3db9","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","backport:skip","v9.0.0","docs","Team:Threat
Hunting","Team: SecuritySolution","APIDocs","Team:Threat
Hunting:Investigations"],"number":192744,"url":"https://github.com/elastic/kibana/pull/192744","mergeCommit":{"message":"Improves
Timeline API docs content (elastic#192744)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#35
by\r\nimproving the Timeline API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
Jatin Kathuria <[email protected]>\r\nCo-authored-by: kibanamachine
<[email protected]>","sha":"9765f73ec2ab4d1ef2406247503b1ceaba1c3db9"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/192744","number":192744,"mergeCommit":{"message":"Improves
Timeline API docs content (elastic#192744)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#35
by\r\nimproving the Timeline API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
Jatin Kathuria <[email protected]>\r\nCo-authored-by: kibanamachine
<[email protected]>","sha":"9765f73ec2ab4d1ef2406247503b1ceaba1c3db9"}}]}]
BACKPORT-->

---------

Co-authored-by: kibanamachine <[email protected]>

x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts

@@ -587,7 +587,9 @@ If asset criticality records already exist for the specified entities, those rec
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-    * Retrieves a clean draft timeline. If a draft timeline does not exist, it is created and returned.
+    * Create a clean draft Timeline or Timeline template for the current user.
+> info
+> If the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
 
     */
   async cleanDraftTimelines(props: CleanDraftTimelinesProps) {
@@ -716,6 +718,9 @@ If a record already exists for the specified entity, that record is overwritten
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Create a new Timeline or Timeline template.
+   */
   async createTimelines(props: CreateTimelinesProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateTimelines`);
     return this.kbnClient
@@ -788,6 +793,9 @@ If a record already exists for the specified entity, that record is overwritten
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete a note from a Timeline using the note ID.
+   */
   async deleteNote(props: DeleteNoteProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteNote`);
     return this.kbnClient
@@ -818,6 +826,9 @@ If a record already exists for the specified entity, that record is overwritten
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete one or more Timelines or Timeline templates.
+   */
   async deleteTimelines(props: DeleteTimelinesProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteTimelines`);
     return this.kbnClient
@@ -1184,6 +1195,9 @@ If a record already exists for the specified entity, that record is overwritten
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Export Timelines as an NDJSON file.
+   */
   async exportTimelines(props: ExportTimelinesProps) {
     this.log.info(`${new Date().toISOString()} Calling API ExportTimelines`);
     return this.kbnClient
@@ -1309,6 +1323,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of the draft Timeline  or Timeline template for the current user. If the user doesn't have a draft Timeline, an empty Timeline is returned.
+   */
   async getDraftTimelines(props: GetDraftTimelinesProps) {
     this.log.info(`${new Date().toISOString()} Calling API GetDraftTimelines`);
     return this.kbnClient
@@ -1377,7 +1394,7 @@ finalize it.
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Gets notes
+   * Get all notes for a given document.
    */
   async getNotes(props: GetNotesProps) {
     this.log.info(`${new Date().toISOString()} Calling API GetNotes`);
@@ -1577,6 +1594,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of an existing saved Timeline or Timeline template.
+   */
   async getTimeline(props: GetTimelineProps) {
     this.log.info(`${new Date().toISOString()} Calling API GetTimeline`);
     return this.kbnClient
@@ -1591,6 +1611,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a list of all saved Timelines or Timeline templates.
+   */
   async getTimelines(props: GetTimelinesProps) {
     this.log.info(`${new Date().toISOString()} Calling API GetTimelines`);
     return this.kbnClient
@@ -1639,6 +1662,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Import Timelines.
+   */
   async importTimelines(props: ImportTimelinesProps) {
     this.log.info(`${new Date().toISOString()} Calling API ImportTimelines`);
     return this.kbnClient
@@ -1724,6 +1750,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Install or update prepackaged Timelines.
+   */
   async installPrepackedTimelines(props: InstallPrepackedTimelinesProps) {
     this.log.info(`${new Date().toISOString()} Calling API InstallPrepackedTimelines`);
     return this.kbnClient
@@ -1814,7 +1843,7 @@ finalize it.
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Updates an existing timeline. This API is used to update the title, description, date range, pinned events, pinned queries, and/or pinned saved queries of an existing timeline.
+   * Update an existing Timeline. You can update the title, description, date range, pinned events, pinned queries, and/or pinned saved queries of an existing Timeline.
    */
   async patchTimeline(props: PatchTimelineProps) {
     this.log.info(`${new Date().toISOString()} Calling API PatchTimeline`);
@@ -1846,6 +1875,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Favorite a Timeline or Timeline template for the current user.
+   */
   async persistFavoriteRoute(props: PersistFavoriteRouteProps) {
     this.log.info(`${new Date().toISOString()} Calling API PersistFavoriteRoute`);
     return this.kbnClient
@@ -1859,6 +1891,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Add a note to a Timeline or update an existing note.
+   */
   async persistNoteRoute(props: PersistNoteRouteProps) {
     this.log.info(`${new Date().toISOString()} Calling API PersistNoteRoute`);
     return this.kbnClient
@@ -1872,6 +1907,9 @@ finalize it.
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Pin an event to an existing Timeline.
+   */
   async persistPinnedEventRoute(props: PersistPinnedEventRouteProps) {
     this.log.info(`${new Date().toISOString()} Calling API PersistPinnedEventRoute`);
     return this.kbnClient

x-pack/solutions/security/plugins/security_solution/common/api/timeline/clean_draft_timelines/clean_draft_timelines_route.schema.yaml

@@ -8,13 +8,15 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: CleanDraftTimelines
-      summary: Retrieves a draft timeline or timeline template.
+      summary: Create a clean draft Timeline or Timeline template
       description: |
-        Retrieves a clean draft timeline. If a draft timeline does not exist, it is created and returned.
+        Create a clean draft Timeline or Timeline template for the current user.
+        > info
+        > If the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
       tags:
         - access:securitySolution
       requestBody:
-        description: The type of timeline to create. Valid values are `default` and `template`.
+        description: The type of Timeline to create. Valid values are `default` and `template`.
         required: true
         content:
           application/json:
@@ -26,13 +28,13 @@ paths:
                   $ref: '../model/components.schema.yaml#/components/schemas/TimelineType'
       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.
+          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:
               schema:
                 $ref: '../model/components.schema.yaml#/components/schemas/PersistTimelineResponse'
         '403':
-          description: Indicates that the user does not have the required permissions to create a draft timeline.
+          description: Indicates that the user does not have the required permissions to create a draft Timeline.
           content:
             application:json:
               schema:
@@ -43,7 +45,7 @@ paths:
                   status_code:
                     type: number
         '409':
-          description: Indicates that there is already a draft timeline with the given timelineId.
+          description: Indicates that there is already a draft Timeline with the given `timelineId`.
           content:
             application:json:
               schema:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/create_timelines/create_timelines_route.schema.yaml

@@ -11,11 +11,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: CreateTimelines
-      summary: Creates a new timeline.
+      summary: Create a Timeline or Timeline template
+      description: Create a new Timeline or Timeline template.
       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 Timeline fields used to create a new Timeline, along with optional fields that will be created if not provided.
         required: true
         content:
           application/json:
@@ -45,13 +46,13 @@ paths:
                   nullable: true
       responses:
         '200':
-          description: Indicates the timeline was successfully created.
+          description: Indicates the Timeline was successfully created.
           content:
             application/json:
               schema:
                 $ref: '../model/components.schema.yaml#/components/schemas/PersistTimelineResponse'
         '405':
-          description: Indicates that there was an error in the timeline creation.
+          description: Indicates that there was an error in the Timeline creation.
           content:
             application/json:
               schema:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/delete_note/delete_note_route.schema.yaml

@@ -8,11 +8,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: DeleteNote
-      summary: Deletes a note from a timeline.
+      summary: Delete a note
+      description: Delete a note from a Timeline using the note ID.
       tags:
         - access:securitySolution
       requestBody:
-        description: The id of the note to delete.
+        description: The ID of the note to delete.
         required: true
         content:
           application/json:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/delete_timelines/delete_timelines_route.schema.yaml

@@ -11,11 +11,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: DeleteTimelines
-      summary: Deletes one or more timelines or timeline templates.
+      summary: Delete Timelines or Timeline templates
+      description: Delete one or more Timelines or Timeline templates.
       tags:
         - access:securitySolution
       requestBody:
-        description: The ids of the timelines or timeline templates to delete.
+        description: The IDs of the Timelines or Timeline templates to delete.
         required: true
         content:
           application/json:
@@ -34,7 +35,7 @@ paths:
                     type: string
       responses:
         '200':
-          description: Indicates the timeline was successfully deleted.
+          description: Indicates the Timeline was successfully deleted.
           content:
             application/json:
               schema:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/export_timelines/export_timelines_route.schema.yaml

@@ -11,7 +11,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: ExportTimelines
-      summary: Exports timelines as an NDJSON file
+      summary: Export Timelines
+      description: Export Timelines as an NDJSON file.
       tags:
         - access:securitySolution
       parameters:
@@ -22,7 +23,7 @@ paths:
             type: string
           description: The name of the file to export
       requestBody:
-        description: The ids of the timelines to export
+        description: The IDs of the Timelines to export.
         required: true
         content:
           application/json:
@@ -36,14 +37,14 @@ paths:
                     type: string
       responses:
         '200':
-          description: Indicates the timelines were successfully exported
+          description: Indicates the Timelines were successfully exported.
           content:
             application/ndjson:
               schema:
                 type: string
-                description: NDJSON of the exported timelines
+                description: NDJSON of the exported Timelines
         '400':
-          description: Indicates that the export size limit was exceeded
+          description: Indicates that the export size limit was exceeded.
           content:
             application/ndjson:
               schema:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_draft_timelines/get_draft_timelines_route.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetDraftTimelines
-      summary: Retrieves the draft timeline for the current user. If the user does not have a draft timeline, an empty timeline is returned.
+      summary: Get draft Timeline or Timeline template details
+      description: Get the details of the draft Timeline  or Timeline template for the current user. If the user doesn't have a draft Timeline, an empty Timeline is returned.
       tags:
         - access:securitySolution
       parameters:
@@ -19,13 +20,13 @@ paths:
             $ref: '../model/components.schema.yaml#/components/schemas/TimelineType'
       responses:
         '200':
-          description: Indicates that the draft timeline was successfully retrieved.
+          description: Indicates that the draft Timeline was successfully retrieved.
           content:
             application/json:
               schema:
                 $ref: '../model/components.schema.yaml#/components/schemas/PersistTimelineResponse'
         '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.
+          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:
               schema:
@@ -36,7 +37,7 @@ paths:
                   status_code:
                     type: number
         '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.
+          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:
               schema:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_notes/get_notes_route.schema.yaml

@@ -8,8 +8,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetNotes
-      description: Gets notes
-      summary: Get all notes for a given document.
+      description: Get all notes for a given document.
+      summary: Get notes
       tags:
         - access:securitySolution
       parameters:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_timeline/get_timeline_route.gen.ts

@@ -25,7 +25,7 @@ export const GetTimelineRequestQuery = z.object({
    */
   template_timeline_id: z.string().optional(),
   /**
-   * The ID of the timeline to retrieve
+   * The ID of the Timeline to retrieve.
    */
   id: z.string().optional(),
 });

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_timeline/get_timeline_route.schema.yaml

@@ -11,7 +11,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetTimeline
-      summary: Get an existing saved timeline or timeline template. This API is used to retrieve an existing saved timeline or timeline template.
+      summary: Get Timeline or Timeline template details
+      description: Get the details of an existing saved Timeline or Timeline template.
       tags:
         - access:securitySolution
       parameters:
@@ -24,10 +25,10 @@ paths:
           name: id
           schema:
             type: string
-          description: The ID of the timeline to retrieve
+          description: The ID of the Timeline to retrieve.
       responses:
         '200':
-          description: Indicates that the (template) timeline was found and returned.
+          description: Indicates that the (template) Timeline was found and returned.
           content:
             application/json:
               schema:

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_timelines/get_timelines_route.schema.yaml

@@ -11,7 +11,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetTimelines
-      summary: This API is used to retrieve a list of existing saved timelines or timeline templates.
+      summary: Get Timelines or Timeline templates
+      description: Get a list of all saved Timelines or Timeline templates.
       tags:
         - access:securitySolution
       parameters:
@@ -62,7 +63,7 @@ paths:
             nullable: true
       responses:
         '200':
-          description: Indicates that the (template) timelines were found and returned.
+          description: Indicates that the (template) Timelines were found and returned.
           content:
             application/json:
               schema: