[DOCS] Refactor admons for multi-parameter options (#57491) (#57540)

Several APIs support options that can be specified as a query parameter or a
request body parameter.

Currently, this is documented using notes, which can get rather lengthy. This
replaces those multiple notes with a single note and a footnote.

docs/reference/search/search.asciidoc

@@ -38,6 +38,10 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
 [[search-search-api-query-params]]
 ==== {api-query-parms-title}
 
+IMPORTANT: Several options for this API can be specified using a query parameter
+or a request body parameter. If both parameters are specified, only the query
+parameter is used.
+
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
 +
 Defaults to `true`.
@@ -75,14 +79,6 @@ Defaults to `open`.
 `explain`::
 (Optional, boolean) If `true`, returns detailed information about score
 computation as part of a hit. Defaults to `false`.
-+
---
-[IMPORTANT]
-====
-You can also specify this value using the `explain` request body parameter. If
-both parameters are specified, only the query parameter is used.
-====
---
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from]
 +
@@ -100,12 +96,6 @@ correct.
 As an alternative to deep paging, we recommend using
 <<request-body-search-scroll,scroll>> or the
 <<request-body-search-search-after,`search_after`>> parameter.
-
-[IMPORTANT]
-====
-You can also specify this value using the `from` request body parameter. If
-both parameters are specified, only the query parameter is used.
-====
 --
 
 `ignore_throttled`::
@@ -139,18 +129,14 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailab
 [[search-api-query-params-q]]
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search-q]
 +
---
 You can use the `q` parameter to run a query parameter search. Query parameter
 searches do not support the full {es} <<query-dsl,Query DSL>> but are handy for
 testing.
-
++
-[IMPORTANT]
+IMPORTANT: The `q` parameter overrides the <<request-body-search-query,`query`>>
-====
-The `q` parameter overrides the <<request-body-search-query,`query`>>
 parameter in the request body. If both parameters are specified, documents
 matching the `query` request body parameter are not returned.	
-====
+
---
 
 `request_cache`::
 (Optional, boolean) If `true`, the caching of search results is enabled for
@@ -177,18 +163,9 @@ this limit using the `search.max_keep_alive` cluster-level setting.
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search_type]
 
 `seq_no_primary_term`::
-+
---
 (Optional, boolean) If `true`, returns sequence number and primary term of the
 last modification of each hit. See <<optimistic-concurrency-control>>.
 
-[IMPORTANT]
-====
-You can also specify this value using the `seq_no_primary_term` request body
-parameter. If both parameters are specified, only the query parameter is used.
-====
---
-
 `size`::
 (Optional, integer) Defines the number of hits to return. Defaults to `10`.
 +
@@ -208,13 +185,7 @@ As an alternative to deep paging, we recommend using
 <<request-body-search-search-after,`search_after`>> parameter.
 
 If the <<search-api-scroll-query-param,`scroll` parameter>> is specified, this
-value cannot be zero (`0`).
+value cannot be `0`.
-
-[IMPORTANT]
-====
-You can also specify this value using the `size` request body parameter. If
-both parameters are specified, only the query parameter is used.
-====
 --
 
 `sort`::
@@ -247,30 +218,13 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=source_includes]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=terminate_after]
 +
---
 Defaults to `0`, which does not terminate query execution early.
 
-[IMPORTANT]
-====
-You can also specify this value using the `terminate_after` request body
-parameter. If both parameters are specified, only the query parameter is used.
-====
---
-
 `timeout`::
-+
---
 (Optional, <<time-units, time units>>) Specifies the period of time to wait
 for a response. If no response is received before the timeout expires, the
 request fails and returns an error. Defaults to no timeout.
 
-[IMPORTANT]
-====
-You can also specify this value using the `timeout` request body
-parameter. If both parameters are specified, only the query parameter is used.
-====
---
-
 `track_scores`::
   (Optional, boolean) If `true`, calculate and return document scores, even if
   the scores are not used for sorting. Defaults to `false`.
@@ -287,19 +241,9 @@ include the total number of hits matching the query.
   by their respective types in the response. Defaults to `true`.
 
 `version`::
-+
---
 (Optional, boolean)
 If `true`, returns document version as part of a hit. Defaults to `false`.
 
-[IMPORTANT]
-====
-You can also specify this value using the `version` request body parameter. If
-both parameters are specified, only the query parameter is used.
-====
---
-
-
 [[search-search-api-request-body]]
 ==== {api-request-body-title}
 
@@ -307,14 +251,6 @@ both parameters are specified, only the query parameter is used.
 `explain`::
 (Optional, boolean) If `true`, returns detailed information about score
 computation as part of a hit. Defaults to `false`.
-+
---
-[IMPORTANT]
-====
-You can also specify this value using the `explain` query parameter. If
-both parameters are specified, only the query parameter is used.
-====
---
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from]
 +
@@ -332,12 +268,6 @@ correct.
 As an alternative to deep paging, we recommend using
 <<request-body-search-scroll,scroll>> or the
 <<request-body-search-search-after,`search_after`>> parameter.
-
-[IMPORTANT]
-====
-You can also specify this value using the `from` query parameter. If both
-parameters are specified, only the query parameter is used.
-====
 --
 
 [[request-body-search-query]]
@@ -347,18 +277,9 @@ parameters are specified, only the query parameter is used.
 
 [[request-body-search-seq-no-primary-term]]
 `seq_no_primary_term`::
-+
---
 (Optional, boolean) If `true`, returns sequence number and primary term of the
 last modification of each hit. See <<optimistic-concurrency-control>>.
 
-[IMPORTANT]
-====
-You can also specify this value using the `seq_no_primary_term` query parameter.
-If both parameters are specified, only the query parameter is used.
-====
---
-
 `size`:: 
 (Optional, integer) The number of hits to return. Defaults to `10`.
 +
@@ -378,55 +299,23 @@ As an alternative to deep paging, we recommend using
 <<request-body-search-search-after,`search_after`>> parameter.
 
 If the <<search-api-scroll-query-param,`scroll` parameter>> is specified, this
-value cannot be zero (`0`).
+value cannot be `0`.
-
-[IMPORTANT]
-====
-You can also specify this value using the `size` query parameter. If both
-parameters are specified, only the query parameter is used.
-====
 --
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=terminate_after]
 +
---
 Defaults to `0`, which does not terminate query execution early.
 
-[IMPORTANT]
-====
-You can also specify this value using the `terminate_after` query parameter. If
-both parameters are specified, only the query parameter is used.
-====
---
-
 `timeout`::
-+
---
 (Optional, <<time-units, time units>>) Specifies the period of time to wait
 for a response. If no response is received before the timeout expires, the
 request fails and returns an error. Defaults to no timeout.
 
-[IMPORTANT]
-====
-You can also specify this value using the `timeout` query parameter. If both
-parameters are specified, only the query parameter is used.
-====
---
-
 [[request-body-search-version]]
 `version`::
-+
---
 (Optional, boolean)
 If `true`, returns document version as part of a hit. Defaults to `false`.
 
-[IMPORTANT]
-====
-You can also specify this value using the `version` query parameter. If both
-parameters are specified, only the query parameter is used.
-====
---
-
 
 [role="child_attributes"]
 [[search-api-response-body]]

docs/reference/snapshot-restore/apis/put-repo-api.asciidoc

@@ -46,22 +46,19 @@ Name of the snapshot repository to register or update.
 [[put-snapshot-repo-api-query-params]]
 ==== {api-query-parms-title}
 
+IMPORTANT: Several options for this API can be specified using a query parameter
+or a request body parameter. If both parameters are specified, only the query
+parameter is used.
+
 `master_timeout`::
 (Optional, <<time-units, time units>>) Specifies the period of time to wait for
 a connection to the master node. If no response is received before the timeout
 expires, the request fails and returns an error. Defaults to `30s`.
-+
-IMPORTANT: You can also specify this value using the `master_timeout` request
-body parameter. If both parameters are specified, only the query parameter is
-used.
 
 `timeout`::
 (Optional, <<time-units, time units>>) Specifies the period of time to wait for
 a response. If no response is received before the timeout expires, the request
 fails and returns an error. Defaults to `30s`.
-+
-IMPORTANT: You can also specify this value using the `timeout` request body
-parameter. If both parameters are specified, only the query parameter is used.
 
 `verify`::
 (Optional, boolean)
@@ -71,9 +68,6 @@ data nodes in the cluster. If `false`, this verification is skipped. Defaults to
 +
 You can manually perform this verification using the
 <<verify-snapshot-repo-api,verify snapshot repository API>>.
-+
-IMPORTANT: You can also specify this value using the `verify` request body
-parameter. If both parameters are specified, only the query parameter is used.
 
 [role="child_attributes"]
 [[put-snapshot-repo-api-request-body]]
@@ -84,18 +78,12 @@ parameter. If both parameters are specified, only the query parameter is used.
 Specifies the period of time to wait for
 a connection to the master node. If no response is received before the timeout
 expires, the request fails and returns an error. Defaults to `30s`.
-+
-IMPORTANT: You can also specify this value using the `master_timeout` query
-parameter. If both parameters are specified, only the query parameter is used.
 
 `timeout`::
 (Optional, <<time-units, time units>>)
 Specifies the period of time to wait for
 a response. If no response is received before the timeout expires, the request
 fails and returns an error. Defaults to `30s`.
-+
-IMPORTANT: You can also specify this value using the `timeout` query
-parameter. If both parameters are specified, only the query parameter is used.
 
 [[put-snapshot-repo-api-request-type]]
 `type`::
@@ -262,6 +250,3 @@ data nodes in the cluster. If `false`, this verification is skipped. Defaults to
 +
 You can manually perform this verification using the
 <<snapshots-repository-verification,verify snapshot repository API>>.
-+
-IMPORTANT: You can also specify this value using the `verify` query
-parameter. If both parameters are specified, only the query parameter is used.