From 01acabb64c089300e8779f5362a5560ba7d0151b Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Fri, 23 Aug 2019 08:13:27 -0400
Subject: [PATCH] [DOCS] Reformat put mapping API docs (#45709)

---
 docs/reference/indices/put-mapping.asciidoc | 127 ++++++++++++++++----
 docs/reference/mapping.asciidoc             |   1 +
 2 files changed, 105 insertions(+), 23 deletions(-)

diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc
index d5edfe51be8..a47f417d6a2 100644
--- a/docs/reference/indices/put-mapping.asciidoc
+++ b/docs/reference/indices/put-mapping.asciidoc
@@ -1,14 +1,15 @@
 [[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": {
@@ -16,19 +17,99 @@ PUT twitter/_mapping <2>
     }
   }
 }
---------------------------------------------------
+----
 // 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}
+
+`PUT /{index}/_mapping`
+
+`PUT /_mapping`
+
+
+[[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:
@@ -36,8 +117,8 @@ For example, we can update the `twitter-1` and `twitter-2` mappings at the same
 [source,js]
 --------------------------------------------------
 # Create the two indices
-PUT twitter-1
-PUT twitter-2
+PUT /twitter-1
+PUT /twitter-2
 
 # Update both mappings
 PUT /twitter-1,twitter-2/_mapping <1>
@@ -50,12 +131,12 @@ PUT /twitter-1,twitter-2/_mapping <1>
 }
 --------------------------------------------------
 // CONSOLE
+// TEST[setup:twitter]
+
 <1> Note that the indices specified (`twitter-1,twitter-2`) follows <<multi-index,multiple index names>> and wildcard format.
 
-
 [[updating-field-mappings]]
-[float]
-==== Updating field mappings
+===== Update an existing field
 
 // tag::put-field-mapping-exceptions[]
 
@@ -79,7 +160,7 @@ For example:
 
 [source,js]
 -----------------------------------
-PUT my_index <1>
+PUT /my_index <1>
 {
   "mappings": {
     "properties": {
@@ -97,7 +178,7 @@ PUT my_index <1>
   }
 }
 
-PUT my_index/_mapping
+PUT /my_index/_mapping
 {
   "properties": {
     "name": {
diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc
index b5d2e6ae37a..de6951f9670 100644
--- a/docs/reference/mapping.asciidoc
+++ b/docs/reference/mapping.asciidoc
@@ -38,6 +38,7 @@ document.
 
 
 [float]
+[[field-datatypes]]
 == Field datatypes
 
 Each field has a data `type` which can be: