[DOCS] Reformats validate API (#46389)

* [DOCS] Reformats validate API.
Co-Authored-By: James Rodewig <james.rodewig@elastic.co>

docs/reference/search/validate.asciidoc

@@ -1,8 +1,73 @@
 [[search-validate]]
 === Validate API
 
-The validate API allows a user to validate a potentially expensive query
+Validates a potentially expensive query without executing it.
-without executing it. We'll use the following test data to explain _validate:
+
+[source,console]
+--------------------------------------------------
+GET twitter/_validate/query?q=user:foo
+--------------------------------------------------
+// TEST[setup:twitter]
+
+
+[[search-validate-api-request]]
+==== {api-request-title}
+
+`GET /<index>/_validate/<query>`
+
+
+[[search-validate-api-desc]]
+==== {api-description-title}
+
+The validate API allows you to validate a potentially expensive query
+without executing it. The query can be sent either as a path parameter or in the 
+request body.
+
+
+[[search-validate-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=query]
+  
+
+[[search-validate-api-query-params]]
+==== {api-query-parms-title}
+
+`all_shards`::
+  (Optional, boolean) If `true`, the validation is executed on all shards 
+  instead of one random shard per index. Defaults to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=df]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
+`explain`::
+  (Optional, boolean) If `true`, the response returns detailed information if an 
+  error has occured. Defautls to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient]
+
+`rewrite`::
+  (Optional, boolean) If `true`, returns a more detailed explanation showing the 
+  actual Lucene query that will be executed. Defaults to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]
+
+
+[[search-validate-api-example]]
+==== {api-examples-title}
 
 [source,console]
 --------------------------------------------------
@@ -12,7 +77,7 @@ PUT twitter/_bulk?refresh
 {"index":{"_id":2}}
 {"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"}
 --------------------------------------------------
-// TESTSETUP
+
 
 When sent a valid query:
 
@@ -20,6 +85,8 @@ When sent a valid query:
 --------------------------------------------------
 GET twitter/_validate/query?q=user:foo
 --------------------------------------------------
+// TEST[continued]
+
 
 The response contains `valid:true`:
 
@@ -29,31 +96,6 @@ The response contains `valid:true`:
 --------------------------------------------------
 
 
-[float]
-=== Request Parameters
-
-When executing exists using the query parameter `q`, the query passed is
-a query string using Lucene query parser. There are additional
-parameters that can be passed:
-
-[cols="<,<",options="header",]
-|=======================================================================
-|Name |Description
-|`df` |The default field to use when no field prefix is defined within the
-query.
-
-|`analyzer` |The analyzer name to be used when analyzing the query string.
-
-|`default_operator` |The default operator to be used, can be `AND` or
-`OR`. Defaults to `OR`.
-
-|`lenient` |If set to true will cause format based failures (like
-providing text to a numeric field) to be ignored. Defaults to false.
-
-|`analyze_wildcard` |Should wildcard and prefix queries be analyzed or
-not. Defaults to `false`.
-|=======================================================================
-
 The query may also be sent in the request body:
 
 [source,console]
@@ -74,13 +116,14 @@ GET twitter/_validate/query
   }
 }
 --------------------------------------------------
+// TEST[continued]
 
 NOTE: The query being sent in the body must be nested in a `query` key, same as
 the <<search-search,search api>> works
 
-If the query is invalid, `valid` will be `false`. Here the query is
+If the query is invalid, `valid` will be `false`. Here the query is invalid 
-invalid because Elasticsearch knows the post_date field should be a date
+because {es} knows the `post_date` field should be a date due to dynamic 
-due to dynamic mapping, and 'foo' does not correctly parse into a date:
+mapping, and 'foo' does not correctly parse into a date:
 
 [source,console]
 --------------------------------------------------
@@ -94,14 +137,17 @@ GET twitter/_validate/query
   }
 }
 --------------------------------------------------
+// TEST[continued]
 
 [source,console-result]
 --------------------------------------------------
 {"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}
 --------------------------------------------------
 
-An `explain` parameter can be specified to get more detailed information
+===== The explain parameter
-about why a query failed:
+
+An `explain` parameter can be specified to get more detailed information about 
+why a query failed:
 
 [source,console]
 --------------------------------------------------
@@ -115,8 +161,10 @@ GET twitter/_validate/query?explain=true
   }
 }
 --------------------------------------------------
+// TEST[continued]
 
-responds with:
+
+The API returns the following response:
 
 [source,console-result]
 --------------------------------------------------
@@ -136,11 +184,11 @@ responds with:
 --------------------------------------------------
 // TESTRESPONSE[s/"error" : "[^\"]+"/"error": "$body.explanations.0.error"/]
 
-When the query is valid, the explanation defaults to the string
+===== The rewrite parameter
-representation of that query. With `rewrite` set to `true`, the explanation
-is more detailed showing the actual Lucene query that will be executed.
 
-For More Like This:
+When the query is valid, the explanation defaults to the string representation 
+of that query. With `rewrite` set to `true`, the explanation is more detailed 
+showing the actual Lucene query that will be executed.
 
 [source,console]
 --------------------------------------------------
@@ -158,7 +206,8 @@ GET twitter/_validate/query?rewrite=true
 --------------------------------------------------
 // TEST[skip:the output is randomized depending on which shard we hit]
 
-Response:
+
+The API returns the following response:
 
 [source,console-result]
 --------------------------------------------------
@@ -179,13 +228,25 @@ Response:
 }
 --------------------------------------------------
 
+
+===== Rewrite and all_shards parameters
+
 By default, the request is executed on a single shard only, which is randomly
 selected. The detailed explanation of the query may depend on which shard is
 being hit, and therefore may vary from one request to another. So, in case of
 query rewrite the `all_shards` parameter should be used to get response from
 all available shards.
 
-For Fuzzy Queries:
+////
+[source,console]
+--------------------------------------------------
+PUT twitter/_bulk?refresh
+{"index":{"_id":1}}
+{"user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch"}
+{"index":{"_id":2}}
+{"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"}
+--------------------------------------------------
+////
 
 [source,console]
 --------------------------------------------------
@@ -201,8 +262,9 @@ GET twitter/_validate/query?rewrite=true&all_shards=true
   }
 }
 --------------------------------------------------
+// TEST[continued]
 
-Response:
+The API returns the following response:
 
 [source,console-result]
 --------------------------------------------------