[DOCS] Reformats explain API (elastic#46857)

* [DOCS] Reformats explain API.
Co-Authored-By: James Rodewig <[email protected]>

Author: szabosteve

docs/reference/search/explain.asciidoc

@@ -1,16 +1,89 @@
 [[search-explain]]
 === Explain API
 
-The explain api computes a score explanation for a query and a specific
+Returns information about why a specific document matches (or doesn't match) a 
+query.
+
+[source,console]
+--------------------------------------------------
+GET /twitter/_explain/0
+{
+      "query" : {
+        "match" : { "message" : "elasticsearch" }
+      }
+}
+--------------------------------------------------
+// TEST[setup:twitter]
+
+
+[[sample-api-request]]
+==== {api-request-title}
+
+`GET /<index>/_explain/<id>`
+`POST /<index>/_explain/<id>`
+
+[[sample-api-desc]]
+==== {api-description-title}
+
+The explain API computes a score explanation for a query and a specific
 document. This can give useful feedback whether a document matches or
 didn't match a specific query.
 
-Note that a single index must be provided to the `index` parameter.
 
-[float]
-==== Usage
+[[sample-api-path-params]]
+==== {api-path-parms-title}
+
+`<id>`::
+  (Required, integer) Defines the document ID.
+  
+`<index>`::
++
+--
+(Required, string)
+Index names used to limit the request.
+
+Only a single index name can be provided to this parameter.
+--
+
+
+[[sample-api-query-params]]
+==== {api-query-parms-title}
+
+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=lenient]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]
 
-Full query example:
+`stored_fields`::
+  (Optional, string) A comma-separated list of stored fields to return in the 
+  response.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-routing]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
+
+
+[[sample-api-request-body]]
+==== {api-request-body-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=query]
+
+
+[[sample-api-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------
@@ -24,7 +97,8 @@ GET /twitter/_explain/0
 // CONSOLE
 // TEST[setup:twitter]
 
-This will yield the following result:
+
+The API returns the following response:
 
 [source,js]
 --------------------------------------------------
@@ -101,10 +175,11 @@ This will yield the following result:
 --------------------------------------------------
 // TESTRESPONSE
 
-There is also a simpler way of specifying the query via the `q`
-parameter. The specified `q` parameter value is then parsed as if the
-`query_string` query was used. Example usage of the `q` parameter in the
-explain api:
+
+There is also a simpler way of specifying the query via the `q` parameter. The 
+specified `q` parameter value is then parsed as if the `query_string` query was 
+used. Example usage of the `q` parameter in the
+explain API:
 
 [source,js]
 --------------------------------------------------
@@ -113,54 +188,5 @@ GET /twitter/_explain/0?q=message:search
 // CONSOLE
 // TEST[setup:twitter]
 
-This will yield the same result as the previous request.
-
-[float]
-==== All parameters:
-
-[horizontal]
-`_source`::
-
-    Set to `true` to retrieve the `_source` of the document explained. You can also
-    retrieve part of the document by using `_source_includes` & `_source_excludes` (see <<get-source-filtering,Get API>> for more details)
-
-`stored_fields`::
-    Allows to control which stored fields to return as part of the
-    document explained.
-
-`routing`::
-    Controls the routing in the case the routing was used
-    during indexing.
-
-`parent`::
-    Same effect as setting the routing parameter.
-
-`preference`::
-    Controls on which shard the explain is executed.
-
-`source`::
-    Allows the data of the request to be put in the query
-    string of the url.
-
-`q`::
-    The query string (maps to the query_string query).
-
-`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. Defaults to the default search analyzer.
-
-`analyze_wildcard`::
-    Should wildcard and prefix queries be analyzed or
-    not. Defaults to false.
-
-`lenient`::
-    If set to true will cause format based failures (like
-    providing text to a numeric field) to be ignored. Defaults to false.
 
-`default_operator`::
-    The default operator to be used, can be AND or
-    OR. Defaults to OR.
+The API returns the same result as the previous request.