[OpenAPI] Edit scroll API

Author: lcawl

docs/overlays/elasticsearch-shared-overlays.yaml

@@ -181,8 +181,6 @@ actions:
           x-displayName: Script - Get languages
         - name: search
           x-displayName: Search
-        - name: scroll
-          x-displayName: Search - Scroll
         - name: terms_enum
           x-displayName: Search - Terms enum
         - name: search_application

specification/_global/scroll/ScrollRequest.ts

@@ -22,9 +22,25 @@ import { ScrollId } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Run a scrolling search.
+ *
+ * IMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the `search_after` parameter with a point in time (PIT).
+ *
+ * The scroll API gets large sets of results from a single scrolling search request.
+ * To get the necessary scroll ID, submit a search API request that includes an argument for the `scroll` query parameter.
+ * The `scroll` parameter indicates how long Elasticsearch should retain the search context for the request.
+ * The search response returns a scroll ID in the `_scroll_id` response body parameter.
+ * You can then use the scroll ID with the scroll API to retrieve the next batch of results for the request.
+ * If the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search.
+ *
+ * You can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context.
+ *
+ * IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.
  * @rest_spec_name scroll
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_tag search
+ * @ext_doc_id scroll-search-results
  */
 export interface Request extends RequestBase {
   path_parts: {