[ML] Updates specs for GET job, job stats, model snapshots, and overa…

…ll buckets APIs (#909)

* [ML] Updates specs for GET job, job stats, model snapshots, and overall buckets APIs.

* [ML] Addresses feedback.

specification/ml/get_job_stats/MlGetJobStatsRequest.ts

@@ -21,15 +21,36 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
+ * Retrieves usage information for anomaly detection jobs.
  * @rest_spec_name ml.get_job_stats
  * @since 5.5.0
  * @stability stable
+ * @cluster_privileges monitor_ml
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier for the anomaly detection job. It can be a job identifier, a
+     * group name, a comma-separated list of jobs, or a wildcard expression. If
+     * you do not specify one of these options, the API returns information for
+     * all anomaly detection jobs.
+     */
     job_id?: Id
   }
   query_parameters: {
+    /**
+     * Specifies what to do when the request:
+     *
+     * 1. Contains wildcard expressions and there are no jobs that match.
+     * 2. Contains the _all string or no identifiers and there are no matches.
+     * 3. Contains wildcard expressions and there are only partial matches.
+     *
+     * The default value is `true`, which returns an empty `jobs` array when
+     * there are no matches and the subset of results when there are partial
+     * matches. If this parameter is `false`, the request returns a `404` status
+     * code when there are no matches or only partial matches.
+     * @server_default true
+     */
     allow_no_jobs?: boolean
   }
 }

specification/ml/get_jobs/MlGetJobsRequest.ts

@@ -21,20 +21,50 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
+ * Retrieves configuration information for anomaly detection jobs.
+ * You can get information for multiple anomaly detection jobs in a single API
+ * request by using a group name, a comma-separated list of jobs, or a wildcard
+ * expression. You can get information for all anomaly detection jobs by using
+ * `_all`, by specifying `*` as the `<job_id>`, or by omitting the `<job_id>`.
  * @rest_spec_name ml.get_jobs
  * @since 5.5.0
  * @stability stable
+ * @cluster_privileges monitor_ml
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Identifier for the anomaly detection job. It can be a job identifier, a
+     * group name, or a wildcard expression. If you do not specify one of these
+     * options, the API returns information for all anomaly detection jobs.
+     */
     job_id?: Ids
   }
   query_parameters: {
-    /** @server_default true */
+    /**
+     * Specifies what to do when the request:
+     *
+     * 1. Contains wildcard expressions and there are no jobs that match.
+     * 2. Contains the _all string or no identifiers and there are no matches.
+     * 3. Contains wildcard expressions and there are only partial matches.
+     *
+     * The default value is `true`, which returns an empty `jobs` array when
+     * there are no matches and the subset of results when there are partial
+     * matches. If this parameter is `false`, the request returns a `404` status
+     * code when there are no matches or only partial matches.
+     * @server_default true
+     */
     allow_no_match?: boolean
-    /** @server_default true */
+    /**
+     * @deprecated 7.10.0
+     */
     allow_no_jobs?: boolean
-    /** @server_default false */
+    /**
+     * Indicates if certain fields should be removed from the configuration on
+     * retrieval. This allows the configuration to be in an acceptable format to
+     * be retrieved and then added to another cluster.
+     * @server_default false
+     */
     exclude_generated?: boolean
   }
 }

specification/ml/get_model_snapshots/MlGetModelSnapshotsRequest.ts

@@ -23,33 +23,60 @@ import { integer } from '@_types/Numeric'
 import { Time } from '@_types/Time'
 
 /**
+ * Retrieves information about model snapshots.
  * @rest_spec_name ml.get_model_snapshots
  * @since 5.4.0
  * @stability stable
+ * @cluster_privileges monitor_ml
  */
 export interface Request extends RequestBase {
   path_parts: {
-    /** Identifier for the anomaly detection job. */
+    /**
+     * Identifier for the anomaly detection job.
+     */
     job_id: Id
-    /** A numerical character string that uniquely identifies the model snapshot. */
+    /**
+     * A numerical character string that uniquely identifies the model snapshot.
+     */
     snapshot_id?: Id
   }
   query_parameters: {
-    /** If true, the results are sorted in descending order. */
+    /**
+     * If true, the results are sorted in descending order.
+     */
     desc?: boolean
-    /** Returns snapshots with timestamps earlier than this time. */
+    /**
+     * Returns snapshots with timestamps earlier than this time.
+     */
     end?: Time
-    /** Skips the specified number of snapshots. */
+    /**
+     * Skips the specified number of snapshots.
+     */
     from?: integer
-    /** Specifies the maximum number of snapshots to obtain. */
+    /**
+     * Specifies the maximum number of snapshots to obtain.
+     */
     size?: integer
-    /** Specifies the sort field for the requested snapshots. By default, the snapshots are sorted by their timestamp. */
+    /**
+     * Specifies the sort field for the requested snapshots. By default, the
+     * snapshots are sorted by their timestamp.
+     */
     sort?: Field
-    /** Returns snapshots with timestamps after this time. */
+    /**
+     * Returns snapshots with timestamps after this time.
+     */
     start?: Time
   }
   body: {
+    /**
+     * Returns snapshots with timestamps after this time. Defaults to unset,
+     * which means results are not limited to specific timestamps.
+     */
     start?: Time
+    /**
+     * Returns snapshots with timestamps earlier than this time. Defaults to
+     * unset, which means results are not limited to specific timestamps.
+     */
     end?: Time
   }
 }