[Docs] Fix Java Api index administration usage (#28133)

The Java API documentation for index administration currenty is wrong because
the PutMappingRequestBuilder#setSource(Object... source) and
CreateIndexRequestBuilder#addMapping(String type, Object... source) methods
delegate to methods that check that the input arguments are valid key/value
pairs:

https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/java-admin-indices.html

This changes the docs so the java api code examples are included from
documentation integration tests so we detect compile and runtime issues earlier.

Closes #28131

docs/java-api/admin/indices/put-mapping.asciidoc

@@ -1,21 +1,13 @@
 [[java-admin-indices-put-mapping]]
+:base-dir: {docdir}/../../core/src/test/java/org/elasticsearch/action/admin/indices/create
+
 ==== Put Mapping
 
 The PUT mapping API allows you to add a new type while creating an index:
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-client.admin().indices().prepareCreate("twitter")   <1>
-        .addMapping("tweet", "{\n" +                <2>
-                "    \"tweet\": {\n" +
-                "      \"properties\": {\n" +
-                "        \"message\": {\n" +
-                "          \"type\": \"text\"\n" +
-                "        }\n" +
-                "      }\n" +
-                "    }\n" +
-                "  }")
-        .get();
+include-tagged::{base-dir}/CreateIndexIT.java[addMapping-create-index-request]
 --------------------------------------------------
 <1> <<java-admin-indices-create-index,Creates an index>> called `twitter`
 <2> It also adds a `tweet` mapping type.
@@ -23,32 +15,9 @@ client.admin().indices().prepareCreate("twitter")   <1>
 
 The PUT mapping API also allows to add a new type to an existing index:
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-client.admin().indices().preparePutMapping("twitter")   <1>
-        .setType("user")                                <2>
-        .setSource("{\n" +                              <3>
-                "  \"properties\": {\n" +
-                "    \"name\": {\n" +
-                "      \"type\": \"text\"\n" +
-                "    }\n" +
-                "  }\n" +
-                "}")
-        .get();
-
-// You can also provide the type in the source document
-client.admin().indices().preparePutMapping("twitter")
-        .setType("user")
-        .setSource("{\n" +
-                "    \"user\":{\n" +                        <4>
-                "        \"properties\": {\n" +
-                "            \"name\": {\n" +
-                "                \"type\": \"text\"\n" +
-                "            }\n" +
-                "        }\n" +
-                "    }\n" +
-                "}")
-        .get();
+include-tagged::{base-dir}/CreateIndexIT.java[putMapping-request-source]
 --------------------------------------------------
 <1> Puts a mapping on existing index called `twitter`
 <2> Adds a `user` mapping type.
@@ -57,20 +26,12 @@ client.admin().indices().preparePutMapping("twitter")
 
 You can use the same API to update an existing mapping:
 
-[source,java]
+["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-client.admin().indices().preparePutMapping("twitter")   <1>
-        .setType("user")                                <2>
-        .setSource("{\n" +                              <3>
-                "  \"properties\": {\n" +
-                "    \"user_name\": {\n" +
-                "      \"type\": \"text\"\n" +
-                "    }\n" +
-                "  }\n" +
-                "}")
-        .get();
+include-tagged::{base-dir}/CreateIndexIT.java[putMapping-request-source-append]
 --------------------------------------------------
 <1> Puts a mapping on existing index called `twitter`
 <2> Updates the `user` mapping type.
 <3> This `user` has now a new field `user_name`
 
+:base-dir!:

server/src/test/java/org/elasticsearch/action/admin/indices/create/CreateIndexIT.java

@@ -20,6 +20,7 @@
 package org.elasticsearch.action.admin.indices.create;
 
 import com.carrotsearch.hppc.cursors.ObjectCursor;
+
 import org.elasticsearch.ElasticsearchException;
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.UnavailableShardsException;
@@ -28,6 +29,7 @@ import org.elasticsearch.action.admin.indices.delete.DeleteIndexResponse;
 import org.elasticsearch.action.search.SearchResponse;
 import org.elasticsearch.action.support.ActiveShardCount;
 import org.elasticsearch.action.support.IndicesOptions;
+import org.elasticsearch.client.Client;
 import org.elasticsearch.cluster.ClusterState;
 import org.elasticsearch.cluster.metadata.IndexMetaData;
 import org.elasticsearch.cluster.metadata.MetaData;
@@ -35,6 +37,7 @@ import org.elasticsearch.cluster.node.DiscoveryNode;
 import org.elasticsearch.common.collect.ImmutableOpenMap;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.TimeValue;
+import org.elasticsearch.common.xcontent.XContentType;
 import org.elasticsearch.env.NodeEnvironment;
 import org.elasticsearch.index.IndexNotFoundException;
 import org.elasticsearch.index.query.RangeQueryBuilder;
@@ -400,4 +403,69 @@ public class CreateIndexIT extends ESIntegTestCase {
         assertThat(e, hasToString(containsString("unknown setting [index.foo]")));
     }
 
+    /**
+    * This test method is used to generate the Put Mapping Java Indices API documentation
+    * at "docs/java-api/admin/indices/put-mapping.asciidoc" so the documentation gets tested
+    * so that it compiles and runs without throwing errors at runtime.
+    */
+    public void testPutMappingDocumentation() throws Exception {
+        Client client = client();
+        // tag::addMapping-create-index-request
+        client.admin().indices().prepareCreate("twitter")  // <1>
+        .addMapping("tweet", "{\n" +                       // <2>
+                "    \"tweet\": {\n" +
+                "      \"properties\": {\n" +
+                "        \"message\": {\n" +
+                "          \"type\": \"text\"\n" +
+                "        }\n" +
+                "      }\n" +
+                "    }\n" +
+                "  }", XContentType.JSON)
+        .get();
+        // end::addMapping-create-index-request
+
+        // we need to delete in order to create a fresh new index with another type
+        client.admin().indices().prepareDelete("twitter").get();
+        client.admin().indices().prepareCreate("twitter").get();
+
+        // tag::putMapping-request-source
+        client.admin().indices().preparePutMapping("twitter")   // <1>
+        .setType("user")                                        // <2>
+        .setSource("{\n" +                                      // <3>
+                "  \"properties\": {\n" +
+                "    \"name\": {\n" +
+                "      \"type\": \"text\"\n" +
+                "    }\n" +
+                "  }\n" +
+                "}", XContentType.JSON)
+        .get();
+
+        // You can also provide the type in the source document
+        client.admin().indices().preparePutMapping("twitter")
+        .setType("user")
+        .setSource("{\n" +
+                "    \"user\":{\n" +                            // <4>
+                "        \"properties\": {\n" +
+                "            \"name\": {\n" +
+                "                \"type\": \"text\"\n" +
+                "            }\n" +
+                "        }\n" +
+                "    }\n" +
+                "}", XContentType.JSON)
+        .get();
+        // end::putMapping-request-source
+
+        // tag::putMapping-request-source-append
+        client.admin().indices().preparePutMapping("twitter")   // <1>
+        .setType("user")                                        // <2>
+        .setSource("{\n" +                                      // <3>
+                "  \"properties\": {\n" +
+                "    \"user_name\": {\n" +
+                "      \"type\": \"text\"\n" +
+                "    }\n" +
+                "  }\n" +
+                "}", XContentType.JSON)
+        .get();
+        // end::putMapping-request-source-append
+    }
 }