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

The Java API documentation for index administration currenty is wrong because
the PutMappingRequestBuilder#setSource(Object... source) an
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,4 +1,5 @@
 [[java-admin-indices-put-mapping]]
+
 ==== Put Mapping
 
 The PUT mapping API allows you to add a new type while creating an index:
@@ -13,32 +14,9 @@ include-tagged::{client-tests}/IndicesDocumentationIT.java[index-with-mapping]
 
 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::{client-tests}/IndicesDocumentationIT.java[putMapping-request-source]
 --------------------------------------------------
 <1> Puts a mapping on existing index called `twitter`
 <2> Adds a `user` mapping type.
@@ -47,20 +25,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::{client-tests}/IndicesDocumentationIT.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/client/documentation/IndicesDocumentationIT.java

@@ -19,13 +19,32 @@
 
 package org.elasticsearch.client.documentation;
 
-import org.elasticsearch.action.admin.indices.create.CreateIndexResponse;
 import org.elasticsearch.client.Client;
+import org.elasticsearch.common.xcontent.XContentType;
 import org.elasticsearch.test.ESIntegTestCase;
 
+/**
+ * This class is used to generate the Java indices administration documentation.
+ * You need to wrap your code between two tags like:
+ * // tag::example[]
+ * // end::example[]
+ *
+ * Where example is your tag name.
+ *
+ * Then in the documentation, you can extract what is between tag and end tags
+ * with ["source","java",subs="attributes,callouts,macros"]
+ * --------------------------------------------------
+ * include-tagged::{client-tests}/IndicesDocumentationIT.java[your-example-tag-here]
+ * --------------------------------------------------
+ */
 public class IndicesDocumentationIT extends ESIntegTestCase {
 
-    public void createMappings() {
+    /**
+     * 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::index-with-mapping
@@ -39,6 +58,50 @@ public void createMappings() {
                         "}")
                 .get();
         // end::index-with-mapping
+
+        // 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
     }
 
 }