[OpenAPI] Edit search operation summaries

Author: lcawl

specification/_doc_ids/table.csv

@@ -531,6 +531,7 @@ search-validate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}
 search-vector-tile-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-vector-tile-api.html
 searchable-snapshots-api-mount-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-mount-snapshot.html
 searchable-snapshots-apis,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-apis.html
+search-templates,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html
 secure-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/secure-settings.html
 security-api-authenticate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-authenticate.html
 security-api-change-password,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-change-password.html

specification/_global/clear_scroll/ClearScrollRequest.ts

@@ -21,7 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { ScrollIds } from '@_types/common'
 
 /**
- * Clears the search context and results for a scrolling search.
+ * Clear a scrolling search.
+ *
+ * Clear the search context and results for a scrolling search.
  * @rest_spec_name clear_scroll
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/close_point_in_time/ClosePointInTimeRequest.ts

@@ -21,7 +21,12 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Closes a point-in-time.
+ * Close a point in time.
+ *
+ * A point in time must be opened explicitly before being used in search requests.
+ * The `keep_alive` parameter tells Elasticsearch how long it should persist.
+ * A point in time is automatically closed when the `keep_alive` period has elapsed.
+ * However, keeping points in time has a cost; close them as soon as they are no lwonger required for search requests.
  * @rest_spec_name close_point_in_time
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/field_caps/FieldCapabilitiesRequest.ts

@@ -23,9 +23,13 @@ import { RuntimeFields } from '@_types/mapping/RuntimeFields'
 import { QueryContainer } from '@_types/query_dsl/abstractions'
 
 /**
- * The field capabilities API returns the information about the capabilities of fields among multiple indices.
- * The field capabilities API returns runtime fields like any other field. For example, a runtime field with a type
- * of keyword is returned as any other field that belongs to the `keyword` family.
+ * Get the field capabilities.
+ *
+ * Get information about the capabilities of fields among multiple indices.
+ *
+ * For data streams, the API returns field capabilities among the stream’s backing indices.
+ * It returns runtime fields like any other field.
+ * For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the `keyword` family.
  * @rest_spec_name field_caps
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/msearch_template/MultiSearchTemplateRequest.ts

@@ -23,12 +23,13 @@ import { long } from '@_types/Numeric'
 import { RequestItem } from './types'
 
 /**
- * Runs multiple templated searches with a single request.
+ * Run multiple templated searches.
  * @rest_spec_name msearch_template
  * @availability stack since=5.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @index_privileges read
  * @doc_tag search
+ * @ext_doc_id search-templates
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/_global/open_point_in_time/OpenPointInTimeRequest.ts

@@ -23,12 +23,17 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
 import { Duration } from '@_types/Time'
 
 /**
- * A search request by default executes against the most recent visible data of the target indices,
+ * Open a point in time.
+ *
+ * A search request by default runs against the most recent visible data of the target indices,
  * which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the
  * state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple
  * search requests using the same point in time. For example, if refreshes happen between
  * `search_after` requests, then the results of those requests might not be consistent as changes happening
  * between searches are only visible to the more recent point in time.
+ * 
+ * A point in time must be opened explicitly before being used in search requests.
+ * The `keep_alive` parameter tells Elasticsearch how long it should persist.
  * @rest_spec_name open_point_in_time
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/rank_eval/RankEvalRequest.ts

@@ -22,7 +22,9 @@ import { ExpandWildcards, Indices } from '@_types/common'
 import { RankEvalMetric, RankEvalRequestItem } from './types'
 
 /**
- * Enables you to evaluate the quality of ranked search results over a set of typical search queries.
+ * Evaluate ranked search results.
+ *
+ * Evaluate the quality of ranked search results over a set of typical search queries.
  * @rest_spec_name rank_eval
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/render_search_template/RenderSearchTemplateRequest.ts

@@ -23,7 +23,9 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Renders a search template as a search request body.
+ * Render a search template.
+ *
+ * Render a search template as a search request body.
  * @rest_spec_name render_search_template
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/search_template/SearchTemplateRequest.ts

@@ -30,11 +30,12 @@ import {
 import { Duration } from '@_types/Time'
 
 /**
- * Runs a search with a search template.
+ * Run a search with a search template.
  * @rest_spec_name search_template
  * @availability stack since=2.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_tag search
+ * @ext_doc_id search-teamplate
  */
 export interface Request extends RequestBase {
   path_parts: {