[DOCS] Adds description to global APIs part 3 (#2271)

Co-authored-by: Abdon Pijpelink <[email protected]>

Author: szabosteve

output/schema/schema.json

@@ -29,25 +29,71 @@ import {
 import { SourceConfigParam } from '@global/search/_types/SourceFilter'
 
 /**
+ * Checks if a document in an index exists.
  * @rest_spec_name exists
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier of the document.
+     */
     id: Id
+    /**
+     * Comma-separated list of data streams, indices, and aliases.
+     * Supports wildcards (`*`).
+     */
     index: IndexName
   }
   query_parameters: {
+    /**
+     * Specifies the node or shard the operation should be performed on.
+     * Random by default.
+     */
     preference?: string
+    /**
+     * If `true`, the request is real-time as opposed to near-real-time.
+     * @server_default true
+     * @doc_id realtime
+     */
     realtime?: boolean
+    /**
+     * If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.
+     * @server_default false
+     */
     refresh?: boolean
+    /**
+     * Target the specified primary shard.
+     * @doc_id routing
+     */
     routing?: Routing
+    /**
+     * `true` or `false` to return the `_source` field or not, or a list of fields to return.
+     */
     _source?: SourceConfigParam
+    /**
+     * A comma-separated list of source fields to exclude in the response.
+     */
     _source_excludes?: Fields
+    /**
+     * A comma-separated list of source fields to include in the response.
+     */
     _source_includes?: Fields
+    /**
+     * List of stored fields to return as part of a hit.
+     * If no fields are specified, no stored fields are included in the response.
+     * If this field is specified, the `_source` parameter defaults to false.
+     */
     stored_fields?: Fields
+    /**
+     * Explicit version number for concurrency control.
+     * The specified version must match the current version of the document for the request to succeed.
+     */
     version?: VersionNumber
+    /**
+     * Specific version type: `external`, `external_gte`.
+     */
     version_type?: VersionType
   }
 }

specification/_global/exists/DocumentExistsRequest.ts

@@ -29,24 +29,65 @@ import {
 import { SourceConfigParam } from '@global/search/_types/SourceFilter'
 
 /**
+ * Checks if a document's `_source` is stored.
  * @rest_spec_name exists_source
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier of the document.
+     */
     id: Id
+    /**
+     * Comma-separated list of data streams, indices, and aliases.
+     * Supports wildcards (`*`).
+     */
     index: IndexName
   }
   query_parameters: {
+    /**
+     * Specifies the node or shard the operation should be performed on.
+     * Random by default.
+     */
     preference?: string
+    /**
+     * If true, the request is real-time as opposed to near-real-time.
+     * @server_default true
+     * @doc_id realtime
+     */
     realtime?: boolean
+    /**
+     * If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.
+     * @server_default false
+     */
     refresh?: boolean
+    /**
+     * Target the specified primary shard.
+     * @doc_id routing
+     */
     routing?: Routing
+    /**
+     * `true` or `false` to return the `_source` field or not, or a list of fields to return.
+     */
     _source?: SourceConfigParam
+    /**
+     * A comma-separated list of source fields to exclude in the response.
+     */
     _source_excludes?: Fields
+    /**
+     * A comma-separated list of source fields to include in the response.
+     */
     _source_includes?: Fields
+    /**
+     * Explicit version number for concurrency control.
+     * The specified version must match the current version of the document for the request to succeed.
+     */
     version?: VersionNumber
+    /**
+     * Specific version type: `external`, `external_gte`.
+     */
     version_type?: VersionType
   }
 }

specification/_global/exists_source/SourceExistsRequest.ts

@@ -24,29 +24,81 @@ import { SourceConfigParam } from '@global/search/_types/SourceFilter'
 import { Operator } from '@_types/query_dsl/Operator'
 
 /**
+ * Returns information about why a specific document matches (or doesn’t match) a query.
  * @rest_spec_name explain
  * @availability stack since=0.0.0 stability=stable
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Defines the document ID.
+     */
     id: Id
+    /**
+     * Index names used to limit the request.
+     * Only a single index name can be provided to this parameter.
+     */
     index: IndexName
   }
   query_parameters: {
+    /**
+     * Analyzer to use for the query string.
+     * This parameter can only be used when the `q` query string parameter is specified.
+     */
     analyzer?: string
+    /**
+     * If `true`, wildcard and prefix queries are analyzed.
+     * @server_default false
+     */
     analyze_wildcard?: boolean
+    /**
+     * The default operator for query string query: `AND` or `OR`.
+     * @server_default OR
+     */
     default_operator?: Operator
+    /**
+     * Field to use as default where no field prefix is given in the query string.
+     */
     df?: string
+    /**
+     * If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
+     * @server_default false
+     */
     lenient?: boolean
+    /**
+     * Specifies the node or shard the operation should be performed on.
+     * Random by default.
+     */
     preference?: string
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * True or false to return the `_source` field or not, or a list of fields to return.
+     */
     _source?: SourceConfigParam
+    /**
+     * A comma-separated list of source fields to exclude from the response.
+     */
     _source_excludes?: Fields
+    /**
+     * A comma-separated list of source fields to include in the response.
+     */
     _source_includes?: Fields
+    /**
+     * A comma-separated list of stored fields to return in the response.
+     */
     stored_fields?: Fields
+    /**
+     * Query in the Lucene query string syntax.
+     */
     q?: string
   }
   body: {
+    /**
+     * Defines the search definition using the Query DSL.
+     */
     query?: QueryContainer
   }
 }

specification/_global/explain/ExplainRequest.ts

@@ -46,7 +46,7 @@ export interface Request extends RequestBase {
      */
     preference?: string
     /**
-     *  Boolean) If true, the request is real-time as opposed to near-real-time.
+     * If `true`, the request is real-time as opposed to near-real-time.
      * @server_default true
      * @doc_id realtime
      */
@@ -73,6 +73,11 @@ export interface Request extends RequestBase {
      * A comma-separated list of source fields to include in the response.
      */
     _source_includes?: Fields
+    /**
+     * List of stored fields to return as part of a hit.
+     * If no fields are specified, no stored fields are included in the response.
+     * If this field is specified, the `_source` parameter defaults to false.
+     */
     stored_fields?: Fields
     /**
      * Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.

specification/_global/get/GetRequest.ts

@@ -33,28 +33,85 @@ import { long } from '@_types/Numeric'
 import { Duration } from '@_types/Time'
 
 /**
+ * Adds a JSON document to the specified data stream or index and makes it searchable.
+ * If the target is an index and the document already exists, the request updates the document and increments its version.
  * @rest_spec_name index
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request<TDocument> extends RequestBase {
   path_parts: {
+    /**
+     * Unique identifier for the document.
+     */
     id?: Id
+    /**
+     * Name of the data stream or index to target.
+     */
     index: IndexName
   }
   query_parameters: {
+    /**
+     * Only perform the operation if the document has this primary term.
+     */
     if_primary_term?: long
+    /**
+     * Only perform the operation if the document has this sequence number.
+     */
     if_seq_no?: SequenceNumber
+    /**
+     * Set to create to only index the document if it does not already exist (put if absent).
+     * If a document with the specified `_id` already exists, the indexing operation will fail.
+     * Same as using the `<index>/_create` endpoint.
+     * Valid values: `index`, `create`.
+     * If document id is specified, it defaults to `index`.
+     * Otherwise, it defaults to `create`.
+     */
     op_type?: OpType
+    /**
+     * ID of the pipeline to use to preprocess incoming documents.
+     * If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.
+     * If a final pipeline is configured it will always run, regardless of the value of this parameter.
+     */
     pipeline?: string
+    /**
+     * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.
+     * Valid values: `true`, `false`, `wait_for`.
+     */
     refresh?: Refresh
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.
+     * @server_default 1m
+     */
     timeout?: Duration
+    /**
+     * Explicit version number for concurrency control.
+     * The specified version must match the current version of the document for the request to succeed.
+     */
     version?: VersionNumber
+    /**
+     * Specific version type: `external`, `external_gte`.
+     */
     version_type?: VersionType
+    /**
+     * The number of shard copies that must be active before proceeding with the operation.
+     * Set to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).
+     * @server_default 1
+     */
     wait_for_active_shards?: WaitForActiveShards
+    /**
+     * If `true`, the destination must be an index alias.
+     * @server_default false
+     */
     require_alias?: boolean
   }
   /** @codegen_name document */
+  /**
+   * Request body contains the JSON source for the document data.
+   */
   body?: TDocument
 }

specification/_global/index/IndexRequest.ts

@@ -31,13 +31,38 @@ import { RequestItem } from './types'
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Comma-separated list of data streams, indices, and aliases to search.
+     * Supports wildcards (`*`).
+     * To search all data streams and indices, omit this parameter or use `*`.
+     */
     index?: Indices
   }
   query_parameters: {
+    /**
+     * If `true`, network round-trips are minimized for cross-cluster search requests.
+     * @server_default true
+     */
     ccs_minimize_roundtrips?: boolean
+    /**
+     * Maximum number of concurrent searches the API can run.
+     */
     max_concurrent_searches?: long
+    /**
+     * The type of the search operation.
+     * Available options: `query_then_fetch`, `dfs_query_then_fetch`.
+     */
     search_type?: SearchType
+    /**
+     * If `true`, the response returns `hits.total` as an integer.
+     * If `false`, it returns `hits.total` as an object.
+     * @server_default false
+     */
     rest_total_hits_as_int?: boolean
+    /**
+     * If `true`, the response prefixes aggregation and suggester names with their respective types.
+     * @server_default false
+     */
     typed_keys?: boolean
   }
   /** @codegen_name search_templates */

specification/_global/msearch_template/MultiSearchTemplateRequest.ts

@@ -26,15 +26,24 @@ import { MultisearchHeader } from '@global/msearch/types'
 export type RequestItem = MultisearchHeader | TemplateConfig
 
 export class TemplateConfig {
-  /** @server_default false */
+  /**
+   * If `true`, returns detailed information about score calculation as part of each hit.
+   * @server_default false */
   explain?: boolean
   /**
    * ID of the search template to use. If no source is specified,
    * this parameter is required.
    */
   id?: Id
+  /**
+   * Key-value pairs used to replace Mustache variables in the template.
+   * The key is the variable name.
+   * The value is the variable value.
+   */
   params?: Dictionary<string, UserDefinedValue>
-  /** @server_default false */
+  /**
+   * If `true`, the query execution is profiled.
+   * @server_default false */
   profile?: boolean
   /**
    * An inline search template. Supports the same parameters as the search API's