Docs: Cut down on high level rest client copy-and-paste-ness (#34125)

* Anchors

* includes

* get settings

* more

* More

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java

@@ -55,22 +55,8 @@ import static org.hamcrest.Matchers.greaterThan;
 import static org.hamcrest.Matchers.notNullValue;
 
 /**
- * This class is used to generate the Java Cluster API 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::{doc-tests}/ClusterClientDocumentationIT.java[example]
- * --------------------------------------------------
- *
- * The column width of the code block is 84. If the code contains a line longer
- * than 84, the line will be cut and a horizontal scroll bar will be displayed.
- * (the code indentation of the tag is not included in the width)
+ * Documentation for Cluster APIs in the high level java client.
+ * Code wrapped in {@code tag} and {@code end} tags is included in the docs.
  */
 public class ClusterClientDocumentationIT extends ESRestHighLevelClientTestCase {
 

docs/java-rest/high-level/cluster/get_settings.asciidoc

@@ -1,16 +1,22 @@
-[[java-rest-high-cluster-get-settings]]
+--
+:api: get-settings
+:request: ClusterGetSettingsRequest
+:response: ClusterGetSettingsResponse
+--
+
+[id="{upid}-{api}"]
 === Cluster Get Settings API
 
 The Cluster Get Settings API allows to get the cluster wide settings.
 
-[[java-rest-high-cluster-get-settings-request]]
+[id="{upid}-{api}-request"]
 ==== Cluster Get Settings Request
 
-A `ClusterGetSettingsRequest`:
+A +{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 
 ==== Optional arguments
@@ -18,75 +24,40 @@ The following arguments can optionally be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-includeDefaults]
+include-tagged::{doc-tests-file}[{api}-request-includeDefaults]
 --------------------------------------------------
 <1> By default only those settings that were explicitly set are returned. Setting this to true also returns
 the default settings.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-local]
+include-tagged::{doc-tests-file}[{api}-request-local]
 --------------------------------------------------
 <1> By default the request goes to the master of the cluster to get the latest results. If local is specified it gets
 the results from whichever node the request goes to.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-masterTimeout]
+include-tagged::{doc-tests-file}[{api}-request-masterTimeout]
 --------------------------------------------------
 <1> Timeout to connect to the master node as a `TimeValue`
 <2> Timeout to connect to the master node as a `String`
 
-[[java-rest-high-cluster-get-settings-sync]]
-==== Synchronous Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute]
---------------------------------------------------
-<1> Execute the request and get back the response in a `ClusterGetSettingsResponse` object.
-
-[[java-rest-high-cluster-get-settings-async]]
-==== Asynchronous Execution
-
-The asynchronous execution of a cluster get settings requires both the
-`ClusterGetSettingsRequest` instance and an `ActionListener` instance to be
-passed to the asynchronous method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute-async]
---------------------------------------------------
-<1> The `ClusterGetSettingsRequest` to execute and the `ActionListener`
-to use when the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
+include::../execution.asciidoc[]
 
-A typical listener for `ClusterGetSettingsResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument
-<2> Called in case of a failure. The raised exception is provided as an argument
-
-[[java-rest-high-cluster-get-settings-response]]
+[id="{upid}-{api}-response"]
 ==== Cluster Get Settings Response
 
-The returned `ClusterGetSettingsResponse` allows to retrieve information about the
+The returned +{response}+ allows to retrieve information about the
 executed operation as follows:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> Get the persistent settings.
 <2> Get the transient settings.
 <3> Get the default settings (returns empty settings if `includeDefaults` was not set to `true`).
 <4> Get the value as a `String` for a particular setting. The order of searching is first in `persistentSettings` then in
 `transientSettings` and finally, if not found in either, in `defaultSettings`.
+

docs/java-rest/high-level/cluster/health.asciidoc

@@ -1,16 +1,22 @@
-[[java-rest-high-cluster-health]]
+--
+:api: health
+:request: ClusterHealthRequest
+:response: ClusterHealthResponse
+--
+
+[id="{upid}-{api}"]
 === Cluster Health API
 
 The Cluster Health API allows getting cluster health.
 
-[[java-rest-high-cluster-health-request]]
+[id="{upid}-{api}-request"]
 ==== Cluster Health Request
 
-A `ClusterHealthRequest`:
+A +{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 There are no required parameters. By default, the client will check all indices and will not wait
 for any events.
@@ -21,14 +27,14 @@ Indices which should be checked can be passed in the constructor:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-ctr]
+include-tagged::{doc-tests-file}[{api}-request-indices-ctr]
 --------------------------------------------------
 
 Or using the corresponding setter method:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-setter]
+include-tagged::{doc-tests-file}[{api}-request-indices-setter]
 --------------------------------------------------
 
 ==== Other parameters
@@ -37,53 +43,53 @@ Other parameters can be passed only through setter methods:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-timeout]
+include-tagged::{doc-tests-file}[{api}-request-timeout]
 --------------------------------------------------
 <1> Timeout for the request as a `TimeValue`. Defaults to 30 seconds
 <2> As a `String`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-master-timeout]
+include-tagged::{doc-tests-file}[{api}-request-master-timeout]
 --------------------------------------------------
 <1> Timeout to connect to the master node as a `TimeValue`. Defaults to the same as `timeout`
 <2> As a `String`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-status]
+include-tagged::{doc-tests-file}[{api}-request-wait-status]
 --------------------------------------------------
 <1> The status to wait (e.g. `green`, `yellow`, or `red`). Accepts a `ClusterHealthStatus` value.
 <2> Using predefined method
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-events]
+include-tagged::{doc-tests-file}[{api}-request-wait-events]
 --------------------------------------------------
 <1> The priority of the events to wait for. Accepts a `Priority` value.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-level]
+include-tagged::{doc-tests-file}[{api}-request-level]
 --------------------------------------------------
-<1> The level of detail of the returned health information. Accepts a `ClusterHealthRequest.Level` value.
+<1> The level of detail of the returned health information. Accepts a +{request}.Level+ value.
 Default value is `cluster`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-relocation]
+include-tagged::{doc-tests-file}[{api}-request-wait-relocation]
 --------------------------------------------------
 <1> Wait for 0 relocating shards. Defaults to `false`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-initializing]
+include-tagged::{doc-tests-file}[{api}-request-wait-initializing]
 --------------------------------------------------
 <1> Wait for 0 initializing shards. Defaults to `false`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-nodes]
+include-tagged::{doc-tests-file}[{api}-request-wait-nodes]
 --------------------------------------------------
 <1> Wait for `N` nodes in the cluster. Defaults to `0`
 <2> Using `>=N`, `<=N`, `>N` and `<N` notation
@@ -91,7 +97,7 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wai
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-active]
+include-tagged::{doc-tests-file}[{api}-request-wait-active]
 --------------------------------------------------
 
 <1> Wait for all shards to be active in the cluster
@@ -99,77 +105,42 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wai
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-local]
+include-tagged::{doc-tests-file}[{api}-request-local]
 --------------------------------------------------
 <1> Non-master node can be used for this request. Defaults to `false`
 
-[[java-rest-high-cluster-health-sync]]
-==== Synchronous Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute]
---------------------------------------------------
-
-[[java-rest-high-cluster-health-async]]
-==== Asynchronous Execution
-
-The asynchronous execution of a cluster health request requires both the
-`ClusterHealthRequest` instance and an `ActionListener` instance to be
-passed to the asynchronous method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-async]
---------------------------------------------------
-<1> The `ClusterHealthRequest` to execute and the `ActionListener` to use
-when the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
-
-A typical listener for `ClusterHealthResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument
-<2> Called in case of a failure. The raised exception is provided as an argument
+include::../execution.asciidoc[]
 
-[[java-rest-high-cluster-health-response]]
+[id="{upid}-{api}-response"]
 ==== Cluster Health Response
 
-The returned `ClusterHealthResponse` contains the next information about the
+The returned +{response}+ contains the next information about the
 cluster:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-general]
+include-tagged::{doc-tests-file}[{api}-response-general]
 --------------------------------------------------
 <1> Name of the cluster
 <2> Cluster status (`green`, `yellow` or `red`)
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-request-status]
+include-tagged::{doc-tests-file}[{api}-response-request-status]
 --------------------------------------------------
 <1> Whether request was timed out while processing
 <2> Status of the request (`OK` or `REQUEST_TIMEOUT`). Other errors will be thrown as exceptions
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-nodes]
+include-tagged::{doc-tests-file}[{api}-response-nodes]
 --------------------------------------------------
 <1> Number of nodes in the cluster
 <2> Number of data nodes in the cluster
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shards]
+include-tagged::{doc-tests-file}[{api}-response-shards]
 --------------------------------------------------
 <1> Number of active shards
 <2> Number of primary active shards
@@ -181,7 +152,7 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-sh
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-task]
+include-tagged::{doc-tests-file}[{api}-response-task]
 --------------------------------------------------
 <1> Maximum wait time of all tasks in the queue
 <2> Number of currently pending tasks
@@ -189,18 +160,18 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-ta
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-indices]
+include-tagged::{doc-tests-file}[{api}-response-indices]
 --------------------------------------------------
 <1> Detailed information about indices in the cluster
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-index]
+include-tagged::{doc-tests-file}[{api}-response-index]
 --------------------------------------------------
 <1> Detailed information about a specific index
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shard-details]
+include-tagged::{doc-tests-file}[{api}-response-shard-details]
 --------------------------------------------------
 <1> Detailed information about a specific shard

docs/java-rest/high-level/cluster/put_settings.asciidoc

@@ -1,16 +1,22 @@
-[[java-rest-high-cluster-put-settings]]
+--
+:api: put-settings
+:request: ClusterUpdateSettingsRequest
+:response: ClusterUpdateSettingsResponse
+--
+
+[id="{upid}-{api}"]
 === Cluster Update Settings API
 
 The Cluster Update Settings API allows to update cluster wide settings.
 
-[[java-rest-high-cluster-put-settings-request]]
+[id="{upid}-{api}-request"]
 ==== Cluster Update Settings Request
 
-A `ClusterUpdateSettingsRequest`:
+A +{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 
 ==== Cluster Settings
@@ -18,7 +24,7 @@ At least one setting to be updated must be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request-cluster-settings]
+include-tagged::{doc-tests-file}[{api}-request-cluster-settings]
 --------------------------------------------------
 <1> Sets the transient settings to be applied
 <2> Sets the persistent setting to be applied
@@ -28,26 +34,26 @@ The settings to be applied can be provided in different ways:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-create-settings]
+include-tagged::{doc-tests-file}[{api}-create-settings]
 --------------------------------------------------
 <1> Creates a transient setting as `Settings`
 <2> Creates a persistent setting as `Settings`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-settings-builder]
+include-tagged::{doc-tests-file}[{api}-settings-builder]
 --------------------------------------------------
 <1> Settings provided as `Settings.Builder`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-settings-source]
+include-tagged::{doc-tests-file}[{api}-settings-source]
 --------------------------------------------------
 <1> Settings provided as `String`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-settings-map]
+include-tagged::{doc-tests-file}[{api}-settings-map]
 --------------------------------------------------
 <1> Settings provided as a `Map`
 
@@ -56,7 +62,7 @@ The following arguments can optionally be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request-timeout]
+include-tagged::{doc-tests-file}[{api}-request-timeout]
 --------------------------------------------------
 <1> Timeout to wait for the all the nodes to acknowledge the settings were applied
 as a `TimeValue`
@@ -65,58 +71,23 @@ as a `String`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request-masterTimeout]
+include-tagged::{doc-tests-file}[{api}-request-masterTimeout]
 --------------------------------------------------
 <1> Timeout to connect to the master node as a `TimeValue`
 <2> Timeout to connect to the master node as a `String`
 
-[[java-rest-high-cluster-put-settings-sync]]
-==== Synchronous Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-execute]
---------------------------------------------------
-
-[[java-rest-high-cluster-put-settings-async]]
-==== Asynchronous Execution
-
-The asynchronous execution of a cluster update settings requires both the
-`ClusterUpdateSettingsRequest` instance and an `ActionListener` instance to be
-passed to the asynchronous method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-execute-async]
---------------------------------------------------
-<1> The `ClusterUpdateSettingsRequest` to execute and the `ActionListener`
-to use when the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
-
-A typical listener for `ClusterUpdateSettingsResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument
-<2> Called in case of a failure. The raised exception is provided as an argument
+include::../execution.asciidoc[]
 
-[[java-rest-high-cluster-put-settings-response]]
+[id="{upid}-{api}-response"]
 ==== Cluster Update Settings Response
 
-The returned `ClusterUpdateSettings` allows to retrieve information about the
+The returned +{response}+ allows to retrieve information about the
 executed operation as follows:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> Indicates whether all of the nodes have acknowledged the request
 <2> Indicates which transient settings have been applied
-<3> Indicates which persistent settings have been applied
+<3> Indicates which persistent settings have been applied

docs/java-rest/high-level/execution.asciidoc

@@ -0,0 +1,48 @@
+////
+This file is included by every high level rest client API documentation page
+so we don't have to copy and paste the same asciidoc over and over again. We
+*do* have to copy and paste the same Java tests over and over again. For now
+this is intentional because it forces us to *write* and execute the tests
+which, while a bit ceremonial, does force us to cover these calls in *some*
+test.
+////
+
+[id="{upid}-{api}-sync"]
+==== Synchronous Execution
+
+When executing a +{request}+ in the following manner, the client waits
+for the +{response}+ to be returned before continuing with code execution:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute]
+--------------------------------------------------
+
+[id="{upid}-{api}-async"]
+==== Asynchronous Execution
+
+Executing a +{request}+ can also be done in an asynchronous fashion so that
+the client can return directly. Users need to specify how the response or
+potential failures will be handled by passing the request and a listener to the
+asynchronous {api} method:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute-async]
+--------------------------------------------------
+<1> The +{request}+ to execute and the `ActionListener` to use when
+the execution completes
+
+The asynchronous method does not block and returns immediately. Once it is
+completed the `ActionListener` is called back using the `onResponse` method
+if the execution successfully completed or using the `onFailure` method if
+it failed.
+
+A typical listener for +{response}+ looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute-listener]
+--------------------------------------------------
+<1> Called when the execution is successfully completed.
+<2> Called when the whole +{request}+ fails.

docs/java-rest/high-level/index.asciidoc

@@ -1,4 +1,6 @@
-[[java-rest-high]]
+:mainid: java-rest-high
+
+[id="{mainid}"]
 = Java High Level REST Client
 
 [partintro]
@@ -31,3 +33,4 @@ include::migration.asciidoc[]
 include::../license.asciidoc[]
 
 :doc-tests!:
+:mainid!:

docs/java-rest/high-level/java-builders.asciidoc

@@ -10,7 +10,7 @@ The query builders are used to create the query to execute within a search reque
 is a query builder for every type of query supported by the Query DSL. Each query builder
 implements the `QueryBuilder` interface and allows to set the specific options for a given
 type of query. Once created, the `QueryBuilder` object can be set as the query parameter of
-`SearchSourceBuilder`. The <<java-rest-high-document-search-request-building-queries, Search Request>>
+`SearchSourceBuilder`. The <<java-rest-high-search-request-building-queries, Search Request>>
 page shows an example of how to build a full search request using `SearchSourceBuilder` and
 `QueryBuilder` objects. The <<java-rest-high-query-builders, Building Search Queries>> page
 gives a list of all available search queries with their corresponding `QueryBuilder` objects
@@ -24,7 +24,7 @@ aggregation (or pipeline aggregation) supported by Elasticsearch. All builders e
 `AggregationBuilder` class (or `PipelineAggregationBuilder`class). Once created, `AggregationBuilder`
 objects can be set as the aggregation parameter of `SearchSourceBuilder`. There is a example
 of how `AggregationBuilder` objects are used with `SearchSourceBuilder` objects to define the aggregations
-to compute with a search query in <<java-rest-high-document-search-request-building-aggs, Search Request>> page.
+to compute with a search query in <<java-rest-high-search-request-building-aggs, Search Request>> page.
 The <<java-rest-high-aggregation-builders, Building Aggregations>> page gives a list of all available
 aggregations with their corresponding `AggregationBuilder` objects and `AggregationBuilders` helper methods.
 

docs/java-rest/high-level/search/search.asciidoc

@@ -1,10 +1,16 @@
-[[java-rest-high-search]]
+--
+:api: search
+:request: SearchRequest
+:response: SearchResponse
+--
+
+[id="{upid}-{api}"]
 === Search API
 
-[[java-rest-high-document-search-request]]
+[id="{upid}-{api}-request"]
 ==== Search Request
 
-The `SearchRequest` is used for any operation that has to do with searching
+The +{request}+ is used for any operation that has to do with searching
 documents, aggregations, suggestions and also offers ways of requesting
 highlighting on the resulting documents.
 
@@ -12,7 +18,7 @@ In its most basic form, we can add a query to the request:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-basic]
+include-tagged::{doc-tests-file}[{api}-request-basic]
 --------------------------------------------------
 
 <1> Creates the `SeachRequest`. Without arguments this runs against all indices.
@@ -20,14 +26,14 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-basic]
 <3> Add a `match_all` query to the `SearchSourceBuilder`.
 <4> Add the `SearchSourceBuilder` to the `SeachRequest`.
 
-[[java-rest-high-search-request-optional]]
+[id="{upid}-{api}-request-optional"]
 ===== Optional arguments
 
-Let's first look at some of the optional arguments of a `SearchRequest`:
+Let's first look at some of the optional arguments of a +{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-indices-types]
+include-tagged::{doc-tests-file}[{api}-request-indices-types]
 --------------------------------------------------
 <1> Restricts the request to an index
 <2> Limits the request to a type
@@ -36,20 +42,20 @@ There are a couple of other interesting optional parameters:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-routing]
+include-tagged::{doc-tests-file}[{api}-request-routing]
 --------------------------------------------------
 <1> Set a routing parameter
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-indicesOptions]
+include-tagged::{doc-tests-file}[{api}-request-indicesOptions]
 --------------------------------------------------
 <1> Setting `IndicesOptions` controls how unavailable indices are resolved and
 how wildcard expressions are expanded
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-preference]
+include-tagged::{doc-tests-file}[{api}-request-preference]
 --------------------------------------------------
 <1> Use the preference parameter e.g. to execute the search to prefer local
 shards. The default is to randomize across shards.
@@ -65,7 +71,7 @@ Here are a few examples of some common options:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-basics]
+include-tagged::{doc-tests-file}[{api}-source-basics]
 --------------------------------------------------
 <1> Create a `SearchSourceBuilder` with default options.
 <2> Set the query. Can be any type of `QueryBuilder`
@@ -77,14 +83,14 @@ Defaults to 10.
 take.
 
 After this, the `SearchSourceBuilder` only needs to be added to the
-`SearchRequest`:
++{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-setter]
+include-tagged::{doc-tests-file}[{api}-source-setter]
 --------------------------------------------------
 
-[[java-rest-high-document-search-request-building-queries]]
+[id="{upid}-{api}-request-building-queries"]
 ===== Building queries
 
 Search queries are created using `QueryBuilder` objects. A `QueryBuilder` exists
@@ -94,7 +100,7 @@ A `QueryBuilder` can be created using its constructor:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builder-ctor]
+include-tagged::{doc-tests-file}[{api}-query-builder-ctor]
 --------------------------------------------------
 <1> Create a full text {ref}/query-dsl-match-query.html[Match Query] that matches
 the text "kimchy" over the field "user".
@@ -104,7 +110,7 @@ of the search query it creates:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builder-options]
+include-tagged::{doc-tests-file}[{api}-query-builder-options]
 --------------------------------------------------
 <1> Enable fuzzy matching on the match query
 <2> Set the prefix length option on the match query
@@ -117,7 +123,7 @@ This class provides helper methods that can be used to create `QueryBuilder` obj
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builders]
+include-tagged::{doc-tests-file}[{api}-query-builders]
 --------------------------------------------------
 
 Whatever the method used to create it, the `QueryBuilder` object must be added
@@ -125,10 +131,10 @@ to the `SearchSourceBuilder` as follows:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-setter]
+include-tagged::{doc-tests-file}[{api}-query-setter]
 --------------------------------------------------
 
-The <<java-rest-high-query-builders, Building Queries>> page gives a list of all available search queries with
+The <<{upid}-query-builders, Building Queries>> page gives a list of all available search queries with
 their corresponding `QueryBuilder` objects and `QueryBuilders` helper methods.
 
 
@@ -138,7 +144,7 @@ The `SearchSourceBuilder` allows to add one or more `SortBuilder` instances. The
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-sorting]
+include-tagged::{doc-tests-file}[{api}-source-sorting]
 --------------------------------------------------
 <1> Sort descending by `_score` (the default)
 <2> Also sort ascending by `_id` field
@@ -149,17 +155,17 @@ By default, search requests return the contents of the document `_source` but li
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-filtering-off]
+include-tagged::{doc-tests-file}[{api}-source-filtering-off]
 --------------------------------------------------
 
 The method also accepts an array of one or more wildcard patterns to control which fields get included or excluded in a more fine grained way:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-filtering-includes]
+include-tagged::{doc-tests-file}[{api}-source-filtering-includes]
 --------------------------------------------------
 
-[[java-rest-high-request-highlighting]]
+[id="{upid}-{api}-request-highlighting"]
 ===== Requesting Highlighting
 
 Highlighting search results can be achieved by setting a `HighlightBuilder` on the
@@ -168,7 +174,7 @@ fields by adding one or more `HighlightBuilder.Field` instances to a `HighlightB
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-highlighting]
+include-tagged::{doc-tests-file}[{api}-request-highlighting]
 --------------------------------------------------
 <1> Creates a new `HighlightBuilder`
 <2> Create a field highlighter for the `title` field
@@ -179,9 +185,9 @@ There are many options which are explained in detail in the Rest API documentati
 API parameters (e.g. `pre_tags`) are usually changed by
 setters with a similar name (e.g. `#preTags(String ...)`).
 
-Highlighted text fragments can <<java-rest-high-retrieve-highlighting,later be retrieved>> from the `SearchResponse`.
+Highlighted text fragments can <<{upid}-{api}-response-highlighting,later be retrieved>> from the +{response}+.
 
-[[java-rest-high-document-search-request-building-aggs]]
+[id="{upid}-{api}-request-building-aggs"]
 ===== Requesting Aggregations
 
 Aggregations can be added to the search by first creating the appropriate
@@ -191,13 +197,13 @@ sub-aggregation on the average age of employees in the company:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations]
+include-tagged::{doc-tests-file}[{api}-request-aggregations]
 --------------------------------------------------
 
-The <<java-rest-high-aggregation-builders, Building Aggregations>> page gives a list of all available aggregations with
+The <<{upid}-aggregation-builders, Building Aggregations>> page gives a list of all available aggregations with
 their corresponding `AggregationBuilder` objects and `AggregationBuilders` helper methods.
 
-We will later see how to <<java-rest-high-retrieve-aggs,access aggregations>> in the `SearchResponse`.
+We will later see how to <<{upid}-{api}-response-aggs,access aggregations>> in the +{response}+.
 
 ===== Requesting Suggestions
 
@@ -207,14 +213,14 @@ need to be added to the top level `SuggestBuilder`, which itself can be set on t
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-suggestion]
+include-tagged::{doc-tests-file}[{api}-request-suggestion]
 --------------------------------------------------
 <1> Creates a new `TermSuggestionBuilder` for the `user` field and
 the text `kmichy`
 <2> Adds the suggestion builder and names it `suggest_user`
 
-We will later see how to <<java-rest-high-retrieve-suggestions,retrieve suggestions>> from the
-`SearchResponse`.
+We will later see how to <<{upid}-{api}-response-suggestions,retrieve suggestions>> from the
++{response}+.
 
 ===== Profiling Queries and Aggregations
 
@@ -223,56 +229,18 @@ a specific search request. in order to use it, the profile flag must be set to t
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling]
---------------------------------------------------
-
-Once the `SearchRequest` is executed the corresponding `SearchResponse` will
-<<java-rest-high-retrieve-profile-results,contain the profiling results>>.
-
-[[java-rest-high-document-search-sync]]
-==== Synchronous Execution
-
-When executing a `SearchRequest` in the following manner, the client waits
-for the `SearchResponse` to be returned before continuing with code execution:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute]
---------------------------------------------------
-
-[[java-rest-high-document-search-async]]
-==== Asynchronous Execution
-
-Executing a `SearchRequest` can also be done in an asynchronous fashion so that
-the client can return directly. Users need to specify how the response or
-potential failures will be handled by passing the request and a listeners to the
-asynchronous search method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute-async]
+include-tagged::{doc-tests-file}[{api}-request-profiling]
 --------------------------------------------------
-<1> The `SearchRequest` to execute and the `ActionListener` to use when
-the execution completes
 
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
+Once the +{request}+ is executed the corresponding +{response}+ will
+<<{upid}-{api}-response-profile,contain the profiling results>>.
 
-A typical listener for `SearchResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed.
-<2> Called when the whole `SearchRequest` fails.
+include::../execution.asciidoc[]
 
-[[java-rest-high-search-response]]
-==== SearchResponse
+[id="{upid}-{api}-response"]
+==== {response}
 
-The `SearchResponse` that is returned by executing the search provides details
+The +{response}+ that is returned by executing the search provides details
 about the search execution itself as well as access to the documents returned.
 First, there is useful information about the request execution itself, like the
 HTTP status code, execution time or whether the request terminated early or timed
@@ -280,7 +248,7 @@ out:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-1]
+include-tagged::{doc-tests-file}[{api}-response-1]
 --------------------------------------------------
 
 Second, the response also provides information about the execution on the
@@ -291,10 +259,10 @@ failures can also be handled by iterating over an array off
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-2]
+include-tagged::{doc-tests-file}[{api}-response-2]
 --------------------------------------------------
 
-[[java-rest-high-retrieve-searchHits]]
+[id="{upid}-{api}-response-search-hits"]
 ===== Retrieving SearchHits
 
 To get access to the returned documents, we need to first get the `SearchHits`
@@ -302,7 +270,7 @@ contained in the response:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-get]
+include-tagged::{doc-tests-file}[{api}-hits-get]
 --------------------------------------------------
 
 The `SearchHits` provides global information about all hits, like total number
@@ -310,7 +278,7 @@ of hits or the maximum score:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-info]
+include-tagged::{doc-tests-file}[{api}-hits-info]
 --------------------------------------------------
 
 Nested inside the `SearchHits` are the individual search results that can
@@ -319,7 +287,7 @@ be iterated over:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit]
+include-tagged::{doc-tests-file}[{api}-hits-singleHit]
 --------------------------------------------------
 
 The `SearchHit` provides access to basic information like index, type, docId and
@@ -327,7 +295,7 @@ score of each search hit:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit-properties]
+include-tagged::{doc-tests-file}[{api}-hits-singleHit-properties]
 --------------------------------------------------
 
 Furthermore, it lets you get back the document source, either as a simple
@@ -338,34 +306,34 @@ cases need to be cast accordingly:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit-source]
+include-tagged::{doc-tests-file}[{api}-hits-singleHit-source]
 --------------------------------------------------
 
-[[java-rest-high-retrieve-highlighting]]
+[id="{upid}-{api}-response-highlighting"]
 ===== Retrieving Highlighting
 
-If <<java-rest-high-request-highlighting,requested>>, highlighted text fragments can be retrieved from each `SearchHit` in the result. The hit object offers
+If <<{upid}-{api}-request-highlighting,requested>>, highlighted text fragments can be retrieved from each `SearchHit` in the result. The hit object offers
 access to a map of field names to `HighlightField` instances, each of which contains one
 or many highlighted text fragments:
 
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-highlighting-get]
+include-tagged::{doc-tests-file}[{api}-request-highlighting-get]
 --------------------------------------------------
 <1> Get the highlighting for the `title` field
 <2> Get one or many fragments containing the highlighted field content
 
-[[java-rest-high-retrieve-aggs]]
+[id="{upid}-{api}-response-aggs"]
 ===== Retrieving Aggregations
 
-Aggregations can be retrieved from the `SearchResponse` by first getting the
+Aggregations can be retrieved from the +{response}+ by first getting the
 root of the aggregation tree, the `Aggregations` object, and then getting the
 aggregation by name.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-get]
+include-tagged::{doc-tests-file}[{api}-request-aggregations-get]
 --------------------------------------------------
 <1> Get the `by_company` terms aggregation
 <2> Get the buckets that is keyed with `Elastic`
@@ -377,7 +345,7 @@ otherwise a `ClassCastException` will be thrown:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-get-wrongCast]
+include-tagged::{doc-tests-file}[search-request-aggregations-get-wrongCast]
 --------------------------------------------------
 <1> This will throw an exception because "by_company" is a `terms` aggregation
 but we try to retrieve it as a `range` aggregation
@@ -388,14 +356,14 @@ needs to happen explicitly:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-asMap]
+include-tagged::{doc-tests-file}[{api}-request-aggregations-asMap]
 --------------------------------------------------
 
 There are also getters that return all top level aggregations as a list:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-asList]
+include-tagged::{doc-tests-file}[{api}-request-aggregations-asList]
 --------------------------------------------------
 
 And last but not least you can iterate over all aggregations and then e.g.
@@ -403,17 +371,17 @@ decide how to further process them based on their type:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-iterator]
+include-tagged::{doc-tests-file}[{api}-request-aggregations-iterator]
 --------------------------------------------------
 
-[[java-rest-high-retrieve-suggestions]]
+[id="{upid}-{api}-response-suggestions"]
 ===== Retrieving Suggestions
 
-To get back the suggestions from a `SearchResponse`, use the `Suggest` object as an entry point and then retrieve the nested suggestion objects:
+To get back the suggestions from a +{response}+, use the `Suggest` object as an entry point and then retrieve the nested suggestion objects:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-suggestion-get]
+include-tagged::{doc-tests-file}[{api}-request-suggestion-get]
 --------------------------------------------------
 <1> Use the `Suggest` class to access suggestions
 <2> Suggestions can be retrieved by name. You need to assign them to the correct
@@ -421,21 +389,21 @@ type of Suggestion class (here `TermSuggestion`), otherwise a `ClassCastExceptio
 <3> Iterate over the suggestion entries
 <4> Iterate over the options in one entry
 
-[[java-rest-high-retrieve-profile-results]]
+[id="{upid}-{api}-response-profile"]
 ===== Retrieving Profiling Results
 
-Profiling results are retrieved from a `SearchResponse` using the `getProfileResults()` method. This
+Profiling results are retrieved from a +{response}+ using the `getProfileResults()` method. This
  method returns a `Map` containing a `ProfileShardResult` object for every shard involved in the
- `SearchRequest` execution. `ProfileShardResult` are stored in the `Map` using a key that uniquely
+ +{request}+ execution. `ProfileShardResult` are stored in the `Map` using a key that uniquely
  identifies the shard the profile result corresponds to.
 
 Here is a sample code that shows how to iterate over all the profiling results of every shard:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-get]
+include-tagged::{doc-tests-file}[{api}-request-profiling-get]
 --------------------------------------------------
-<1> Retrieve the `Map` of `ProfileShardResult` from the `SearchResponse`
+<1> Retrieve the `Map` of `ProfileShardResult` from the +{response}+
 <2> Profiling results can be retrieved by shard's key if the key is known, otherwise it might be simpler
  to iterate over all the profiling results
 <3> Retrieve the key that identifies which shard the `ProfileShardResult` belongs to
@@ -446,7 +414,7 @@ executed against the underlying Lucene index:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-queries]
+include-tagged::{doc-tests-file}[{api}-request-profiling-queries]
 --------------------------------------------------
 <1> Retrieve the list of `QueryProfileShardResult`
 <2> Iterate over each `QueryProfileShardResult`
@@ -456,7 +424,7 @@ Each `QueryProfileShardResult` gives access to the detailed query tree execution
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-queries-results]
+include-tagged::{doc-tests-file}[{api}-request-profiling-queries-results]
 --------------------------------------------------
 <1> Iterate over the profile results
 <2> Retrieve the name of the Lucene query
@@ -470,7 +438,7 @@ The `QueryProfileShardResult` also gives access to the profiling information for
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-queries-collectors]
+include-tagged::{doc-tests-file}[{api}-request-profiling-queries-collectors]
 --------------------------------------------------
 <1> Retrieve the profiling result of the Lucene collector
 <2> Retrieve the name of the Lucene collector
@@ -485,7 +453,7 @@ to the detailed aggregations tree execution:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-aggs]
+include-tagged::{doc-tests-file}[{api}-request-profiling-aggs]
 --------------------------------------------------
 <1> Retrieve the `AggregationProfileShardResult`
 <2> Iterate over the aggregation profile results

docs/java-rest/high-level/supported-apis.asciidoc

@@ -46,6 +46,8 @@ The Java High Level REST Client supports the following Search APIs:
 * <<java-rest-high-rank-eval>>
 * <<java-rest-high-explain>>
 
+:upid: {mainid}
+:doc-tests-file: {doc-tests}/SearchDocumentationIT.java
 include::search/search.asciidoc[]
 include::search/scroll.asciidoc[]
 include::search/multi-search.asciidoc[]
@@ -137,6 +139,8 @@ The Java High Level REST Client supports the following Cluster APIs:
 * <<java-rest-high-cluster-get-settings>>
 * <<java-rest-high-cluster-health>>
 
+:upid: {mainid}-cluster
+:doc-tests-file: {doc-tests}/ClusterClientDocumentationIT.java
 include::cluster/put_settings.asciidoc[]
 include::cluster/get_settings.asciidoc[]
 include::cluster/health.asciidoc[]
@@ -309,3 +313,15 @@ The Java High Level REST Client supports the following Graph APIs:
 * <<java-rest-high-x-pack-graph-explore>>
 
 include::graph/explore.asciidoc[]
+
+////
+Clear attributes that we use to document that APIs included above so they
+don't leak into the rest of the documentation.
+////
+--
+:api!:
+:request!:
+:response!:
+:doc-tests-file!:
+:upid!:
+--