[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

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

@@ -26,12 +26,14 @@
 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;
 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.index.IndexNotFoundException;
 import org.elasticsearch.index.query.RangeQueryBuilder;
 import org.elasticsearch.test.ESIntegTestCase;
@@ -343,4 +345,70 @@ public void testIndexNameInResponse() {
 
         assertEquals("Should have index name in response", "foo", response.index());
     }
+
+    /**
+     * 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
+     }
 }

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

@@ -1,54 +1,23 @@
 [[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.
 
 
 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!: