[DOCS] Adds description to global APIs part 2 (#2270)

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

Author: szabosteve

output/schema/schema.json

@@ -30,25 +30,66 @@ import {
 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 create
  * @availability stack since=5.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.
+     * If the target doesn’t exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.
+     * If the target doesn’t exist and doesn’t match a data stream template, this request creates the index.
+     */
     index: IndexName
   }
   query_parameters: {
+    /**
+     * 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`.
+     * @server_default false
+     */
     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
   }
-  /** @codegen_name document */
+  /**
+   * Request body contains the JSON source for the document data.
+   * @codegen_name document */
   body?: TDocument
 }

specification/_global/create/CreateRequest.ts

@@ -32,23 +32,60 @@ import { long } from '@_types/Numeric'
 import { Duration } from '@_types/Time'
 
 /**
+ * Removes a JSON document from the specified index.
  * @rest_spec_name delete
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Unique identifier for the document.
+     */
     id: Id
+    /**
+     * Name of the target index.
+     */
     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
+    /**
+     * 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`.
+     * @server_default false
+     */
     refresh?: Refresh
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * Period to wait 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
   }
 }

specification/_global/delete/DeleteRequest.ts

@@ -34,48 +34,176 @@ import { Duration } from '@_types/Time'
 import { Operator } from '@_types/query_dsl/Operator'
 
 /**
+ * Deletes documents that match the specified query.
  * @rest_spec_name delete_by_query
  * @availability stack since=5.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 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 or indices, omit this parameter or use `*` or `_all`.
+     */
     index: Indices
   }
   query_parameters: {
+    /**
+     * If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.
+     * This behavior applies even if the request targets other open indices.
+     * For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.
+     * @server_default true
+     */
     allow_no_indices?: boolean
+    /**
+     * Analyzer to use for the query string.
+     */
     analyzer?: string
+    /**
+     * If `true`, wildcard and prefix queries are analyzed.
+     * @server_default false
+     */
     analyze_wildcard?: boolean
+    /**
+     * What to do if delete by query hits version conflicts: `abort` or `proceed`.
+     * @server_default abort
+     */
     conflicts?: Conflicts
+    /**
+     * 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
+    /**
+     * Type of index that wildcard patterns can match.
+     * If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
+     * Supports comma-separated values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.
+     * @server_default open
+     */
     expand_wildcards?: ExpandWildcards
     from?: long
+    /**
+     * If `false`, the request returns an error if it targets a missing or closed index.
+     * @server_default false
+     */
     ignore_unavailable?: boolean
+    /**
+     * 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
+    /**
+     * Maximum number of documents to process.
+     * Defaults to all documents.
+     */
     max_docs?: long
+    /**
+     * Specifies the node or shard the operation should be performed on.
+     * Random by default.
+     */
     preference?: string
+    /**
+     * If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.
+     * @server_default false
+     */
     refresh?: boolean
+    /**
+     * If `true`, the request cache is used for this request.
+     * Defaults to the index-level setting.
+     */
     request_cache?: boolean
+    /**
+     * The throttle for this request in sub-requests per second.
+     */
     requests_per_second?: float
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * Query in the Lucene query string syntax.
+     */
     q?: string
+    /**
+     * Period to retain the search context for scrolling.
+     */
     scroll?: Duration
+    /**
+     * Size of the scroll request that powers the operation.
+     * @server_default 1000
+     */
     scroll_size?: long
+    /**
+     * Explicit timeout for each search request.
+     * Defaults to no timeout.
+     */
     search_timeout?: Duration
+    /**
+     * The type of the search operation.
+     * Available options: `query_then_fetch`, `dfs_query_then_fetch`.
+     */
     search_type?: SearchType
+    /**
+     * The number of slices this task should be divided into.
+     * @server_default 1
+     */
     slices?: Slices
+    /**
+     * A comma-separated list of <field>:<direction> pairs.
+     */
     sort?: string[]
+    /**
+     * Specific `tag` of the request for logging and statistical purposes.
+     */
     stats?: string[]
+    /**
+     * Maximum number of documents to collect for each shard.
+     * If a query reaches this limit, Elasticsearch terminates the query early.
+     * Elasticsearch collects documents before sorting.
+     * Use with caution.
+     * Elasticsearch applies this parameter to each shard handling the request.
+     * When possible, let Elasticsearch perform early termination automatically.
+     * Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
+     */
     terminate_after?: long
+    /**
+     * Period each deletion request waits for active shards.
+     * @server_default 1m
+     */
     timeout?: Duration
+    /**
+     * If `true`, returns the document version as part of a hit.
+     */
     version?: boolean
+    /**
+     * 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 request blocks until the operation is complete.
+     * @server_default true
+     */
     wait_for_completion?: boolean
   }
   body: {
+    /**
+     * The maximum number of documents to delete.
+     */
     max_docs?: long
+    /**
+     * Specifies the documents to delete using the Query DSL.
+     */
     query?: QueryContainer
+    /**
+     * Slice the request manually using the provided slice ID and total number of slices.
+     */
     slice?: SlicedScroll
   }
 }

specification/_global/delete_by_query/DeleteByQueryRequest.ts

@@ -27,9 +27,15 @@ import { float } from '@_types/Numeric'
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The ID for the task.
+     */
     task_id: TaskId
   }
   query_parameters: {
+    /**
+     * The throttle for this request in sub-requests per second.
+     */
     requests_per_second?: float
   }
 }

specification/_global/delete_by_query_rethrottle/DeleteByQueryRethrottleRequest.ts

@@ -22,16 +22,30 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Deletes a stored script or search template.
  * @rest_spec_name delete_script
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier for the stored script or search template.
+     */
     id: Id
   }
   query_parameters: {
+    /**
+     * Period to wait for a connection to the master node.
+     * If no response is received before the timeout expires, the request fails and returns an error.
+     * @server_default 30s
+     */
     master_timeout?: Duration
+    /**
+     * Period to wait for a response.
+     * If no response is received before the timeout expires, the request fails and returns an error.
+     * @server_default 30s
+     */
     timeout?: Duration
   }
 }

specification/_global/delete_script/DeleteScriptRequest.ts

@@ -22,12 +22,16 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Retrieves a stored script or search template.
  * @rest_spec_name get_script
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier for the stored script or search template.
+     */
     id: Id
   }
   query_parameters: {