[DOCS] Reformats multi search API (#46256)

* [DOCS] Reformats multi search API.

Co-Authored-By: James Rodewig <james.rodewig@elastic.co>

docs/reference/search/multi-search.asciidoc

@@ -1,13 +1,22 @@
 [[search-multi-search]]
 === Multi Search API
 
-The multi search API allows to execute several search requests within
-the same API. The endpoint for it is `_msearch`.
+Executes several searches with a single API request.
 
-The format of the request is similar to the bulk API format and makes
-use of the newline delimited JSON (NDJSON) format. The structure is as
-follows (the structure is specifically optimized to reduce parsing if
-a specific search ends up redirected to another node):
+[[search-multi-search-api-request]]
+==== {api-request-title}
+
+`GET /<index>/_msearch`
+
+
+[[search-multi-search-api-desc]]
+==== {api-description-title}
+
+The multi search AP executes several searches from a single API request.
+The format of the request is similar to the bulk API format and makes use 
+of the newline delimited JSON (NDJSON) format. The structure is as follows (the 
+structure is specifically optimized to reduce parsing if a specific search ends 
+up redirected to another node):
 
 [source,js]
 --------------------------------------------------
@@ -22,9 +31,67 @@ body\n
 may be preceded by a carriage return `\r`. When sending requests to this endpoint the
 `Content-Type` header should be set to `application/x-ndjson`.
 
-The header part includes which index / indices to search on, the `search_type`, `preference`,
-and `routing`. The body includes the typical search body request (including the `query`,
-`aggregations`, `from`, `size`, and so on). Here is an example:
+[[search-multi-search-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+
+[[search-multi-search-api-request-body]]
+==== {api-request-body-title}
+
+`aggregations`::
+  (Optional, object) Specifies aggregations.
+  
+include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
+  
+`max_concurrent_searches`::
+  (Optional, integer) Specifies the maximum number of concurrent searches the 
+  multi search API will execute. This default is based on the number of data 
+  nodes and the default search thread pool size.
+  
+`max_concurrent_shard_requests`::
+  (Optional, integer) Specifies the maximum number of concurrent shard requests 
+  that each sub search request will execute per node. This parameter should be 
+  used to protect a single request from overloading a cluster (for example a 
+  default request will hit all indices in a cluster which could cause shard 
+  request rejections if the number of shards per node is high). Defaults to `5`. 
+  In certain scenarios parallelism isn't achieved through concurrent request 
+  such that this protection will result in poor performance. For instance in an 
+  environment where only a very low number of concurrent search requests are 
+  expected it might help to increase this value to a higher number.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
+  
+`query`::
+  (Optional, <<query-dsl,query object>>) Defines the search definition using the 
+  <<query-dsl,Query DSL>>.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
+
+`size`:: 
+  (Optional, integer) The number of hits to return. Defaults to `10`.
+
+
+[[search-multi-search-api-response-body]]
+==== {api-response-body-title}
+
+`responses`::
+  (array) Includes the search response and status code for each search request 
+  matching its order in the original multi search request. If there was a  
+  complete failure for a specific search request, an object with `error` message 
+  and corresponding status code will be returned in place of the actual search 
+  response.
+
+
+[[search-multi-search-api-example]]
+==== {api-examples-title}
+
+The header part includes which index / indices to search on, the `search_type`, 
+`preference`, and `routing`. The body includes the typical search body request 
+(including the `query`, `aggregations`, `from`, `size`, and so on).
 
 [source,js]
 --------------------------------------------------
@@ -51,11 +118,6 @@ $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch --d
 Note, the above includes an example of an empty header (can also be just
 without any content) which is supported as well.
 
-The response returns a `responses` array, which includes the search
-response and status code for each search request matching its order in
-the original multi search request. If there was a complete failure for that
-specific search request, an object with `error` message and corresponding
-status code will be returned in place of the actual search response.
 
 The endpoint allows to also search against an index/indices in the URI itself,
 in which case it will be used as the default unless explicitly defined otherwise
@@ -81,33 +143,19 @@ against the `twitter2` index.
 The `search_type` can be set in a similar manner to globally apply to
 all search requests.
 
-The msearch's `max_concurrent_searches` request parameter can be used to control
-the maximum number of concurrent searches the multi search api will execute.
-This default is based on the number of data nodes and the default search thread pool size.
-
-The request parameter `max_concurrent_shard_requests` can be used to control
-the maximum number of concurrent shard requests that each sub search request
-will execute per node. This parameter should be used to protect a single
-request from overloading a cluster (e.g., a default request will hit all
-indices in a cluster which could cause shard request rejections if the number
-of shards per node is high). This default value is `5`.In certain scenarios
-parallelism isn't achieved through concurrent request such that this protection
-will result in poor performance. For instance in an environment where only a
-very low number of concurrent search requests are expected it might help to
-increase this value to a higher number.
-
-[float]
+
 [[msearch-security]]
 ==== Security
 
 See <<url-access-control>>
 
-[float]
+
 [[template-msearch]]
 ==== Template support
 
 Much like described in <<search-template>> for the _search resource, _msearch
-also provides support for templates. Submit them like follows:
+also provides support for templates. Submit them like follows for inline 
+templates:
 
 [source,js]
 -----------------------------------------------
@@ -120,7 +168,6 @@ GET _msearch/template
 // CONSOLE
 // TEST[setup:twitter]
 
-for inline templates.
 
 You can also create search templates:
 
@@ -143,6 +190,7 @@ POST /_scripts/my_template_1
 // CONSOLE
 // TEST[setup:twitter]
 
+
 [source,js]
 ------------------------------------------
 POST /_scripts/my_template_2
@@ -162,7 +210,7 @@ POST /_scripts/my_template_2
 // CONSOLE
 // TEST[continued]
 
-and later use them in a _msearch:
+You can use search templates in a _msearch:
 
 [source,js]
 -----------------------------------------------
@@ -175,7 +223,10 @@ GET _msearch/template
 // CONSOLE
 // TEST[continued]
 
-[float]
+
 [[multi-search-partial-responses]]
 ==== Partial responses
-To ensure fast responses, the multi search API will respond with partial results if one or more shards fail. See <<shard-failures, Shard failures>> for more information.
+
+To ensure fast responses, the multi search API will respond with partial results 
+if one or more shards fail. See <<shard-failures, Shard failures>> for more 
+information.