Add Cluster/Allocation/Explain Query Param Example

Extends the documentation for the `cluster/allocation/explain` API after query parameter support was added in #129342. A second example request was provided with all four query parameters and an empty request body.

Author: joshua-adams-1

specification/_json_spec/cluster.allocation_explain.json

@@ -19,6 +19,22 @@
       ]
     },
     "params": {
+      "current_node": {
+        "type": "string",
+        "description": "Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node"
+      },
+      "index": {
+        "type": "IndexName",
+        "description": "Specifies the name of the index that you would like an explanation for"
+      },
+      "primary": {
+        "type": "boolean",
+        "description": "If true, returns explanation for the primary shard for the given shard ID"
+      },
+      "shard": {
+        "type": "integer",
+        "description": "Specifies the ID of the shard that you would like an explanation for"
+      },
       "master_timeout": {
         "type": "time",
         "description": "Timeout for connection to master node"

specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts

@@ -25,6 +25,7 @@ import { Duration } from '@_types/Time'
 /**
  * Explain the shard allocations.
  * Get explanations for shard allocations in the cluster.
+ * This API accepts the current_node, index, primary and shard parameters via the request body, or via query parameters, but not via both at the same time.
  * For unassigned shards, it provides an explanation for why the shard is unassigned.
  * For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.
  * This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.

specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample1.yaml

@@ -1,4 +1,4 @@
-# summary:
+summary: All parameters in the request body
 method_request: GET _cluster/allocation/explain
 description: Run `GET _cluster/allocation/explain` to get an explanation for a shard's current allocation.
 # type: request

specification/cluster/allocation_explain/examples/request/ClusterAllocationExplainRequestExample2.yaml

@@ -0,0 +1,54 @@
+summary: Query Parameters
+method_request: GET _cluster/allocation/explain
+description: >
+  Run `GET _cluster/allocation/explain?index="my-index-000001"&shard=0&primary=false&current_node="my-node` to get an explanation for a shard's current allocation. No parameters are required in the request body
+# type: request
+value: |-
+  {}
+alternatives:
+  - language: Python
+    code: |-
+      resp = client.cluster.allocation_explain(
+          index="my-index-000001",
+          shard=0,
+          primary=False,
+          current_node="my-node",
+      )
+  - language: JavaScript
+    code: |-
+      const response = await client.cluster.allocationExplain({
+        index: "my-index-000001",
+        shard: 0,
+        primary: false,
+        current_node: "my-node",
+      });
+  - language: Ruby
+    code: |-
+      response = client.cluster.allocation_explain(
+        index: "my-index-000001",
+        shard: 0,
+        primary: false,
+        current_node: "my-node",
+        body: {}
+      )
+  - language: PHP
+    code: |-
+      $resp = $client->cluster()->allocationExplain([
+          "index" => "my-index-000001",
+          "shard" => 0,
+          "primary" => false,
+          "current_node" => "my-node",
+          "body" => [],
+      ]);
+  - language: curl
+    code:
+      'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY"
+      "$ELASTICSEARCH_URL/_cluster/allocation/explain?index="my-index-000001"&shard=0&primary=false&current_node="my-node"'
+  - language: Java
+    code: |
+      client.cluster().allocationExplain(a -> a
+          .currentNode("my-node")
+          .index("my-index-000001")
+          .primary(false)
+          .shard(0)
+      );