[DOCS] Reformat get field mapping API docs (#45700)

Author: jrodewig

docs/reference/indices/get-field-mapping.asciidoc

@@ -1,15 +1,70 @@
 [[indices-get-field-mapping]]
-=== Get Field Mapping
+=== Get field mapping API
+++++
+<titleabbrev>Get field mapping</titleabbrev>
+++++
 
-The get field mapping API allows you to retrieve mapping definitions for one or more fields.
-This is useful when you do not need the complete type mapping returned by
-the <<indices-get-mapping>> API.
+Retrieves <<mapping,mapping definitions>> for one or more fields. This is useful
+if you don't need the <<indices-get-mapping,complete mapping>> of an index or
+your index contains a large number of fields.
 
-For example, consider the following mapping:
+[source,js]
+----
+GET /twitter/_mapping/field/user
+----
+// CONSOLE
+// TEST[setup:twitter]
+
+
+[[get-field-mapping-api-request]]
+==== {api-request-title}
+
+`GET /_mapping/field/<field>`
+
+`GET /<index>/_mapping/field/<field>`
+
+
+[[get-field-mapping-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+`<field>`::
+(Optional, string) Comma-separated list or wildcard expression of fields used to
+limit returned information.
+
+
+[[get-field-mapping-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]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+`include_defaults`::
+(Optional, boolean) If `true`, the response includes default mapping values.
+Defaults to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
+
+
+[[get-field-mapping-api-example]]
+==== {api-examples-title}
+
+[[get-field-mapping-api-basic-ex]]
+===== Example with index setup
+
+You can provide field mappings when creating a new index. The following
+<<indices-create-index, create index>> API request creates the `publications`
+index with several field mappings.
 
 [source,js]
 --------------------------------------------------
-PUT publications
+PUT /publications
 {
     "mappings": {
         "properties": {
@@ -26,7 +81,6 @@ PUT publications
     }
 }
 --------------------------------------------------
-// TESTSETUP
 // CONSOLE
 
 The following returns the mapping of the field `title` only:
@@ -36,8 +90,9 @@ The following returns the mapping of the field `title` only:
 GET publications/_mapping/field/title
 --------------------------------------------------
 // CONSOLE
+// TEST[continued]
 
-For which the response is:
+The API returns the following response:
 
 [source,js]
 --------------------------------------------------
@@ -58,30 +113,8 @@ For which the response is:
 --------------------------------------------------
 // TESTRESPONSE
 
-[float]
-==== Multiple Indices and Fields
-
-The get field mapping API can be used to get the mapping of multiple fields from more than one index
-with a single call. General usage of the API follows the
-following syntax: `host:port/{index}/_mapping/field/{field}` where
-`{index}` and `{field}` can stand for comma-separated list of names or wild cards. To
-get mappings for all indices you can use `_all` for `{index}`. The
-following are some examples:
-
-[source,js]
---------------------------------------------------
-GET /twitter,kimchy/_mapping/field/message
-
-GET /_all/_mapping/field/message,user.id
-
-GET /_all/_mapping/field/*.id
---------------------------------------------------
-// CONSOLE
-// TEST[setup:twitter]
-// TEST[s/^/PUT kimchy\nPUT book\n/]
-
-[float]
-==== Specifying fields
+[[get-field-mapping-api-specific-fields-ex]]
+===== Specifying fields
 
 The get mapping api allows you to specify a comma-separated list of fields.
 
@@ -92,6 +125,7 @@ For instance to select the `id` of the `author` field, you must use its full nam
 GET publications/_mapping/field/author.id,abstract,name
 --------------------------------------------------
 // CONSOLE
+// TEST[continued]
 
 returns:
 
@@ -129,6 +163,7 @@ The get field mapping API also supports wildcard notation.
 GET publications/_mapping/field/a*
 --------------------------------------------------
 // CONSOLE
+// TEST[continued]
 
 returns:
 
@@ -167,11 +202,24 @@ returns:
 --------------------------------------------------
 // TESTRESPONSE
 
-[float]
-==== Other options
+[[get-field-mapping-api-multi-index-ex]]
+===== Multiple indices and fields
 
-[horizontal]
-`include_defaults`::
+The get field mapping API can be used to get the mapping of multiple fields from more than one index
+with a single call. General usage of the API follows the
+following syntax: `host:port/<index>/_mapping/field/<field>` where
+`<index>` and `<field>` can stand for comma-separated list of names or wild cards. To
+get mappings for all indices you can use `_all` for `<index>`. The
+following are some examples:
+
+[source,js]
+--------------------------------------------------
+GET /twitter,kimchy/_mapping/field/message
 
-    adding `include_defaults=true` to the query string will cause the response
-    to include default values, which are normally suppressed.
+GET /_all/_mapping/field/message,user.id
+
+GET /_all/_mapping/field/*.id
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:twitter]
+// TEST[s/^/PUT kimchy\nPUT book\n/]