Adds async search API request and response examples (#2780)

Co-authored-by: lcawl <[email protected]>

Author: szabosteve

docs/overlays/elasticsearch-serverless-openapi-overlays.yaml

@@ -11,8 +11,24 @@ actions:
         **Technical preview**  
         This functionality is in technical preview and may be changed or removed in a future release.
         Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+  - target: "$.components['requestBodies']['async_search.submit']"
+    description: "Add example for asynch search submit request"
+    update: 
+      content:
+        application/json:
+          examples:
+            asyncSearchSubmitResponseExample1:
+              $ref: "../../specification/async_search/submit/AsyncSearchSubmitRequestExample1.json"
+  - target: "$.components['responses']['async_search.submit#200']"
+    description: "Add example for asynch search submit response"
+    update: 
+      content:
+        application/json:
+          examples:
+            asyncSearchSubmitResponseExample1:
+              $ref: "../../specification/async_search/submit/AsyncSearchSubmitResponseExample1.json"
   - target: "$.paths['/_transform/{transform_id}']['put']"
-    description: "Update create transform operation"
+    description: "Add examples for create transform operation"
     update: 
       requestBody: 
         content: 
@@ -29,5 +45,3 @@ actions:
               examples:
                 createTransformResponseExample1:
                   $ref: "../../specification/transform/put_transform/examples/200_response/PutTransformResponseExample1.json"
-               
-

specification/async_search/get/AsyncSearchGetResponseExample1.json

@@ -0,0 +1,7 @@
+{
+  "summary": "A succesful response when retrieving the results of a previously submitted async search request given its identifier.",
+  "description": "",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"id\" : \"FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=\",\n  \"is_partial\" : false,\n  \"is_running\" : false,\n  \"start_time_in_millis\" : 1583945890986,\n  \"expiration_time_in_millis\" : 1584377890986,\n  \"completion_time_in_millis\" : 1583945903130,\n  \"response\" : {\n    \"took\" : 12144,\n    \"timed_out\" : false,\n    \"num_reduce_phases\" : 46,\n    \"_shards\" : {\n      \"total\" : 562,\n      \"successful\" : 188,\n      \"skipped\" : 0,\n      \"failed\" : 0\n    },\n    \"hits\" : {\n      \"total\" : {\n        \"value\" : 456433,\n        \"relation\" : \"eq\"\n      },\n      \"max_score\" : null,\n      \"hits\" : [ ]\n    },\n    \"aggregations\" : {\n      \"sale_date\" :  {\n        \"buckets\" : []\n      }\n    }\n  }\n}"
+}

specification/async_search/get/AsyncSearchGetResponseExample2.json

@@ -0,0 +1,7 @@
+{
+  "summary": "A succesful response when retrieving the status of a previously submitted and completed async search without the results.",
+  "description": "For an async search that has been completed, the status response has an additional `completion_status` field that shows the status code of the completed async search which was – in this case – a success.",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"id\" : \"FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=\",\n  \"is_running\" : false,\n  \"is_partial\" : false,\n  \"start_time_in_millis\" : 1583945890986,\n  \"expiration_time_in_millis\" : 1584377890986,\n  \"_shards\" : {\n      \"total\" : 562,\n      \"successful\" : 562,\n      \"skipped\" : 0,\n      \"failed\" : 0\n  },\n \"completion_status\" : 200\n}"
+}

specification/async_search/get/AsyncSearchGetResponseExample3.json

@@ -0,0 +1,7 @@
+{
+  "summary": "A succesful response when retrieving the status of a previously submitted and completed async search without the results.",
+  "description": "For an async search that has been completed, the status response has an additional `completion_status` field that shows the status code of the completed async search which was completed – in this case – with an error.",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"id\" : \"FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=\",\n  \"is_running\" : false,\n  \"is_partial\" : true,\n  \"start_time_in_millis\" : 1583945890986,\n  \"expiration_time_in_millis\" : 1584377890986,\n  \"_shards\" : {\n      \"total\" : 562,\n      \"successful\" : 450,\n      \"skipped\" : 0,\n      \"failed\" : 112\n  },\n \"completion_status\" : 503\n}"
+}

specification/async_search/status/AsyncSearchStatusResponseExample1.json

@@ -0,0 +1,7 @@
+{
+  "summary": "A succesful response when retrieving the status of a previously submitted async search without the results.",
+  "description": "",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"id\" : \"FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=\",\n  \"is_running\" : true,\n  \"is_partial\" : true,\n  \"start_time_in_millis\" : 1583945890986,\n  \"expiration_time_in_millis\" : 1584377890986,\n  \"_shards\" : {\n      \"total\" : 562,\n      \"successful\" : 188,\n      \"skipped\" : 0,\n      \"failed\" : 0\n  }\n}"
+}

specification/async_search/submit/AsyncSearchSubmitRequestExample1.json

@@ -0,0 +1,7 @@
+{
+  "summary": "Performs a search request asynchronously.",
+  "method_request": "POST /sales*/_async_search?size=0",
+  "description": "Accepts the same parameters and request body as the search API.",
+  "type": "request",
+  "value": "{\n  \"sort\": [\n    { \"date\": { \"order\": \"asc\" } }\n  ],\n  \"aggs\": {\n    \"sale_date\": {\n      \"date_histogram\": {\n        \"field\": \"date\",\n        \"calendar_interval\": \"1d\"\n      }\n    }\n  }\n}"
+}

specification/async_search/submit/AsyncSearchSubmitResponseExample1.json

@@ -0,0 +1,7 @@
+{
+  "summary": "A successful response when performing search asynchronously.",
+  "description": "",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"id\" : \"FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=\",\n  \"is_partial\" : true,\n  \"is_running\" : true,\n  \"start_time_in_millis\" : 1583945890986,\n  \"expiration_time_in_millis\" : 1584377890986,\n  \"response\" : {\n    \"took\" : 1122,\n    \"timed_out\" : false,\n    \"num_reduce_phases\" : 0,\n    \"_shards\" : {\n      \"total\" : 562,\n      \"successful\" : 3,\n      \"skipped\" : 0,\n      \"failed\" : 0\n    },\n    \"hits\" : {\n      \"total\" : {\n        \"value\" : 157483,\n        \"relation\" : \"gte\"\n      },\n      \"max_score\" : null,\n      \"hits\" : [ ]\n    }\n  }\n}"
+}