Add Watcher API examples (#3489) (#3495)

Co-authored-by: István Zoltán Szabó <szabosteve@gmail.com>
(cherry picked from commit 2da56ac)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -789,12 +789,6 @@
       ],
       "response": []
     },
-    "watcher.stop": {
-      "request": [
-        "Request: missing json spec query parameter 'master_timeout'"
-      ],
-      "response": []
-    },
     "watcher.update_settings": {
       "request": [
         "Missing request & response"

output/schema/schema.json

@@ -493,6 +493,7 @@ run-as-privilege,https://www.elastic.co/guide/en/elasticsearch/reference/{branch
 runtime-search-request,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/runtime-search-request.html
 script-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/script-processor.html
 scroll-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results
+search-after,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after
 search-aggregations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations.html
 search-aggregations-bucket-adjacency-matrix-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-adjacency-matrix-aggregation.html
 search-aggregations-bucket-autodatehistogram-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-autodatehistogram-aggregation.html

output/schema/validation-errors.json

@@ -3,4 +3,4 @@ description: A successful response for creating an auto-follow pattern.
 # type: response
 # response_code: 200
 value:
-  acknowledged": true
+  acknowledged: true

output/typescript/types.ts

@@ -92,6 +92,12 @@ export class ExecutionResultInput {
 }
 
 export class ExecutionThreadPool {
+  /**
+   * The largest size of the execution thread pool, which indicates the largest number of concurrent running watches.
+   */
   max_size: long
+  /**
+   * The number of watches that were triggered and are currently queued.
+   */
   queue_size: long
 }

specification/_doc_ids/table.csv

@@ -28,13 +28,24 @@ import { Name, Names } from '@_types/common'
  *
  * IMPORTANT: If the specified watch is currently being executed, this API will return an error
  * The reason for this behavior is to prevent overwriting the watch status from a watch execution.
+ *
+ * Acknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`.
+ * This happens when the condition of the watch is not met (the condition evaluates to false).
  * @rest_spec_name watcher.ack_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
+ * @doc_id watcher-api-ack-watch
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The watch identifier.
+     */
     watch_id: Name
+    /**
+     * A comma-separated list of the action identifiers to acknowledge.
+     * If you omit this parameter, all of the actions of the watch are acknowledged.
+     */
     action_id?: Names
   }
 }

specification/ccr/put_auto_follow_pattern/examples/response/PutAutoFollowPatternResponseExample1.yaml

@@ -0,0 +1,33 @@
+# summary:
+description: A successful response from `POST _watcher/watch/my_watch/_ack`.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "status": {
+      "state": {
+        "active": true,
+        "timestamp": "2015-05-26T18:04:27.723Z"
+      },
+      "last_checked": "2015-05-26T18:04:27.753Z",
+      "last_met_condition": "2015-05-26T18:04:27.763Z",
+      "actions": {
+        "test_index": {
+          "ack" : {
+            "timestamp": "2015-05-26T18:04:27.713Z",
+            "state": "acked"
+          },
+          "last_execution" : {
+            "timestamp": "2015-05-25T18:04:27.733Z",
+            "successful": true
+          },
+          "last_successful_execution" : {
+            "timestamp": "2015-05-25T18:04:27.773Z",
+            "successful": true
+          }
+        }
+      },
+      "execution_state": "executed",
+      "version": 2
+    }
+  }

specification/watcher/_types/Execution.ts

@@ -26,10 +26,14 @@ import { Name } from '@_types/common'
  * @rest_spec_name watcher.activate_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
+ * @doc_id watcher-api-activate-watch
  * @ext_doc_id watcher-works
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The watch identifier.
+     */
     watch_id: Name
   }
 }