From eb4507060a2b2f6f18beb5ebf1687b871ff6eb26 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?=
 <istvan.szabo@elastic.co>
Date: Wed, 4 Sep 2019 11:34:30 +0200
Subject: [PATCH] [DOCS] Reformats search shards API (#46240)

* [DOCS] Reformats search shards API
Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
---
 docs/reference/search/search-shards.asciidoc | 81 +++++++++++++-------
 1 file changed, 52 insertions(+), 29 deletions(-)

diff --git a/docs/reference/search/search-shards.asciidoc b/docs/reference/search/search-shards.asciidoc
index 9912a791af138..288f8b7545ec8 100644
--- a/docs/reference/search/search-shards.asciidoc
+++ b/docs/reference/search/search-shards.asciidoc
@@ -1,17 +1,59 @@
 [[search-shards]]
 === Search Shards API
 
+Returns the indices and shards that a search request would be executed against.
+
+[source,js]
+--------------------------------------------------
+GET /twitter/_search_shards
+--------------------------------------------------
+// CONSOLE
+// TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards":5}}\n/]
+
+
+[[search-shards-api-request]]
+==== {api-request-title}
+
+`GET /<index>/_search_shards`
+
+
+[[search-shards-api-desc]]
+==== {api-description-title}
+
 The search shards api returns the indices and shards that a search request would
 be executed against. This can give useful feedback for working out issues or
 planning optimizations with routing and shard preferences. When filtered aliases
-are used, the filter is returned as part of the `indices` section [5.1.0] Added in 5.1.0.
+are used, the filter is returned as part of the `indices` section.
+
 
-The `index` may be a single value, or comma-separated.
+[[search-shards-api-path-params]]
+==== {api-path-parms-title}
 
-[float]
-==== Usage
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
 
-Full example:
+
+[[search-shards-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+--
+Defaults to `open`.
+--
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
+
+
+[[search-shards-api-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------
@@ -20,7 +62,7 @@ GET /twitter/_search_shards
 // CONSOLE
 // TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards":5}}\n/]
 
-This will yield the following result:
+The API returns the following result:
 
 [source,js]
 --------------------------------------------------
@@ -96,7 +138,7 @@ This will yield the following result:
 // TESTRESPONSE[s/bU_KLGJISbW0RejwnwDPKw/$body.shards.3.0.allocation_id.id/]
 // TESTRESPONSE[s/DMs7_giNSwmdqVukF7UydA/$body.shards.4.0.allocation_id.id/]
 
-And specifying the same request, this time with a routing value:
+Specifying the same request, this time with a routing value:
 
 [source,js]
 --------------------------------------------------
@@ -105,7 +147,7 @@ GET /twitter/_search_shards?routing=foo,bar
 // CONSOLE
 // TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards":5}}\n/]
 
-This will yield the following result:
+The API returns the following result:
 
 [source,js]
 --------------------------------------------------
@@ -145,24 +187,5 @@ This will yield the following result:
 // TESTRESPONSE[s/0TvkCyF7TAmM1wHP4a42-A/$body.shards.1.0.allocation_id.id/]
 // TESTRESPONSE[s/fMju3hd1QHWmWrIgFnI4Ww/$body.shards.0.0.allocation_id.id/]
 
-This time the search will only be executed against two of the shards, because
-routing values have been specified.
-
-[float]
-==== All parameters:
-
-[horizontal]
-`routing`::
-    A comma-separated list of routing values to take into account when
-    determining which shards a request would be executed against.
-
-`preference`::
-    Controls a `preference` of which shard replicas to execute the search
-    request on. By default, the operation is randomized between the shard
-    replicas. See the link:search-request-body.html#request-body-search-preference[preference]
-    documentation for a list of all acceptable values.
-
-`local`::
-    A boolean value whether to read the cluster state locally in order to
-    determine where shards are allocated instead of using the Master node's
-    cluster state.
\ No newline at end of file
+The search will only be executed against two of the shards, because outing 
+values have been specified.