[DOCS] Reformat put mapping API docs

docs/reference/indices/put-mapping.asciidoc

@@ -1,61 +1,48 @@
 [[indices-put-mapping]]
-=== Put Mapping
+=== Put mapping API
+++++
+<titleabbrev>Put mapping</titleabbrev>
+++++
 
-The PUT mapping API allows you to add fields to an existing index or to change search only settings of existing fields.
+Adds new fields to an existing index or changes the search settings of existing
+fields.
 
 [source,js]
---------------------------------------------------
-PUT twitter <1>
-{}
-
-PUT twitter/_mapping <2>
+----
+PUT /twitter/_mapping
 {
   "properties": {
     "email": {
       "type": "keyword"
     }
   }
 }
---------------------------------------------------
+----
 // CONSOLE
-<1> <<indices-create-index,Creates an index>> called `twitter` without any mapping.
-<2> Uses the PUT mapping API to add a new field called `email`.
+// TEST[setup:twitter]
 
-More information on how to define mappings can be found in the <<mapping,mapping>> section.
+NOTE: Before 7.0.0, the 'mappings' definition used to include a type name.
+Although specifying types in requests is now deprecated, a type can still be
+provided if the request parameter `include_type_name` is set. For more details,
+please see <<removal-of-types>>.
 
-NOTE: Before 7.0.0, the 'mappings' definition used to include a type name. Although specifying
-types in requests is now deprecated, a type can still be provided if the request parameter
-include_type_name is set. For more details, please see <<removal-of-types>>.
 
-[float]
-==== Multi-index
+[[put-mapping-api-request]]
+==== {api-request-title}
 
-The PUT mapping API can be applied to multiple indices with a single request.
-For example, we can update the `twitter-1` and `twitter-2` mappings at the same time:
+`PUT /{index}/_mapping`
 
-[source,js]
---------------------------------------------------
-# Create the two indices
-PUT twitter-1
-PUT twitter-2
+`PUT /_mapping`
 
-# Update both mappings
-PUT /twitter-1,twitter-2/_mapping <1>
-{
-  "properties": {
-    "user_name": {
-      "type": "text"
-    }
-  }
-}
---------------------------------------------------
-// CONSOLE
-<1> Note that the indices specified (`twitter-1,twitter-2`) follows <<multi-index,multiple index names>> and wildcard format.
 
+[[put-mapping-api-desc]]
+==== {api-description-title}
+
+You can use the put mapping API to add fields to an existing index or to change
+the search settings of existing fields.
 
 [[updating-field-mappings]]
-[float]
-==== Updating field mappings
+===== Restrictions for existing fields
 
 // tag::put-field-mapping-exceptions[]
 
@@ -75,11 +62,112 @@ you only want to rename a field, consider adding an <<alias, `alias`>> field.
 
 // end::put-field-mapping-exceptions[]
 
+
+[[put-mapping-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
++
+To update the mapping of all indices, omit this parameter or use a value of
+`_all`.
+
+
+[[put-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]
++
+Defaults to `open`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+
+[[put-mapping-api-request-body]]
+==== {api-request-body-title}
+
+`properties`::
++
+--
+(Required, <<mapping,mapping object>>) Mapping for a field. For new
+fields, this mapping can include:
+
+* Field name
+* <<field-datatypes,Field datatype>>
+* <<mapping-params,Mapping parameters>>
+
+For existing fields, see <<updating-field-mappings>>.
+--
+
+
+[[put-mapping-api-example]]
+==== {api-examples-title}
+
+[[put-field-mapping-api-basic-ex]]
+===== Example with index setup
+
+The put mapping API requires an existing index. The following
+<<indices-create-index, create index>> API request creates the `publications`
+index with no mapping.
+
+[source,js]
+----
+PUT /publications
+----
+// CONSOLE
+
+The following put mapping API request adds `title`, a new <<text,`text`>> field,
+to the `publications` index.
+
+[source,js]
+----
+PUT /publications/_mapping
+{
+  "properties": {
+    "title":  { "type": "text"}
+  }
+}
+----
+// CONSOLE
+// TEST[continued]
+
+[[put-mapping-api-multi-ex]]
+===== Multiple indices
+
+The PUT mapping API can be applied to multiple indices with a single request.
+For example, we can update the `twitter-1` and `twitter-2` mappings at the same time:
+
+[source,js]
+--------------------------------------------------
+# Create the two indices
+PUT /twitter-1
+PUT /twitter-2
+
+# Update both mappings
+PUT /twitter-1,twitter-2/_mapping <1>
+{
+  "properties": {
+    "user_name": {
+      "type": "text"
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:twitter]
+
+<1> Note that the indices specified (`twitter-1,twitter-2`) follows <<multi-index,multiple index names>> and wildcard format.
+
 For example:
 
 [source,js]
 -----------------------------------
-PUT my_index <1>
+PUT /my_index <1>
 {
   "mappings": {
     "properties": {
@@ -97,7 +185,7 @@ PUT my_index <1>
   }
 }
 
-PUT my_index/_mapping
+PUT /my_index/_mapping
 {
   "properties": {
     "name": {

docs/reference/mapping.asciidoc

@@ -38,6 +38,7 @@ document.
 
 
 [float]
+[[field-datatypes]]
 == Field datatypes
 
 Each field has a data `type` which can be: