[DOCS] Reformats Field capabilities API (#46866)

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

docs/reference/search/field-caps.asciidoc

@@ -1,70 +1,108 @@
 [[search-field-caps]]
 === Field Capabilities API
 
-The field capabilities API allows to retrieve the capabilities of fields among multiple indices.
-
-The field capabilities API by default executes on all indices:
+Allows you to retrieve the capabilities of fields among multiple indices.
 
 [source,console]
 --------------------------------------------------
-GET _field_caps?fields=rating
+GET /_field_caps?fields=rating
 --------------------------------------------------
 
-The request can also be restricted to specific indices:
 
-[source,console]
---------------------------------------------------
-GET twitter/_field_caps?fields=rating
---------------------------------------------------
-// TEST[setup:twitter]
+[[search-field-caps-api-request]]
+==== {api-request-title}
 
-Supported request options:
+`GET /_field_caps` 
 
-[horizontal]
-`fields`::  A list of fields to compute stats for. The field name supports wildcard notation. For example, using `text_*`
-            will cause all fields that match the expression to be returned.
+`POST /_field_caps` 
 
-[float]
-==== Field Capabilities
+`GET /<index>/_field_caps` 
 
-The field capabilities API returns the following information per field:
+`POST /<index>/_field_caps`
 
-[horizontal]
-`searchable`::
 
-Whether this field is indexed for search on all indices.
+[[search-field-caps-api-desc]]
+==== {api-description-title}
 
-`aggregatable`::
 
-Whether this field can be aggregated on all indices.
+The field capabilities API returns the information about the capabilities of 
+fields among multiple indices.
 
-`indices`::
 
-The list of indices where this field has the same type,
-or null if all indices have the same type for the field.
+[[search-field-caps-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+
+[[search-field-caps-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=fields]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+`include_unmapped`::
+  (Optional, boolean) If `true`, unmapped fields are included in the response. 
+  Defaults to `false`.
 
-`non_searchable_indices`::
 
-The list of indices where this field is not searchable,
-or null if all indices have the same definition for the field.
+[[search-field-caps-api-response-body]]
+==== {api-response-body-title}
+  
+
+
+`searchable`::
+  Whether this field is indexed for search on all indices.
+
+`aggregatable`::
+  Whether this field can be aggregated on all indices.
+
+`indices`::
+  The list of indices where this field has the same type, or null if all indices 
+  have the same type for the field.
+
+`non_searchable_indices`::
+  The list of indices where this field is not searchable, or null if all indices 
+  have the same definition for the field.
 
 `non_aggregatable_indices`::
+  The list of indices where this field is not aggregatable, or null if all 
+  indices have the same definition for the field.
 
-The list of indices where this field is not aggregatable,
-or null if all indices have the same definition for the field.
 
+[[search-field-caps-api-example]]
+==== {api-examples-title}
 
-[float]
-==== Response format
 
-Request:
+The request can be restricted to specific indices:
+
+[source,console]
+--------------------------------------------------
+GET twitter/_field_caps?fields=rating
+--------------------------------------------------
+// TEST[setup:twitter]
+
+
+The next example API call requests information about the `rating` and the 
+`title` fields:
 
 [source,console]
 --------------------------------------------------
 GET _field_caps?fields=rating,title
 --------------------------------------------------
 
-[source,js]
+The API returns the following response:
+
+[source,console-result]
 --------------------------------------------------
 {
     "indices": ["index1", "index2", "index3", "index4", "index5"],
@@ -93,7 +131,7 @@ GET _field_caps?fields=rating,title
     }
 }
 --------------------------------------------------
-// NOTCONSOLE
+// TESTRESPONSE[skip:historically skipped]
 
 <1> The field `rating` is defined as a long in `index1` and `index2`
 and as a `keyword` in `index3` and `index4`.
@@ -101,8 +139,6 @@ and as a `keyword` in `index3` and `index4`.
 <3> The field `rating` is not searchable in `index4`.
 <4> The field `title` is defined as `text` in all indices.
 
-[float]
-==== Unmapped fields
 
 By default unmapped fields are ignored. You can include them in the response by
 adding a parameter called `include_unmapped` in the request:
@@ -112,10 +148,10 @@ adding a parameter called `include_unmapped` in the request:
 GET _field_caps?fields=rating,title&include_unmapped
 --------------------------------------------------
 
-In which case the response will contain an entry for each field that is present in
-some indices but not all:
+In which case the response will contain an entry for each field that is present 
+in some indices but not all:
 
-[source,js]
+[source,console-result]
 --------------------------------------------------
 {
     "indices": ["index1", "index2", "index3"],
@@ -154,7 +190,7 @@ some indices but not all:
     }
 }
 --------------------------------------------------
-// NOTCONSOLE
+// TESTRESPONSE[skip:historically skipped]
 
 <1> The `rating` field is unmapped` in `index5`.
 <2> The `title` field is unmapped` in `index5`.