[DOCS] Reformat refresh API docs (#46667) (#47589)

docs/reference/how-to/indexing-speed.asciidoc

@@ -43,8 +43,7 @@ The operation that consists of making changes visible to search - called a
 <<indices-refresh,refresh>> - is costly, and calling it often while there is
 ongoing indexing activity can hurt indexing speed.
 
-By default, Elasticsearch runs this operation every second, but only on
+include::{docdir}/indices/refresh.asciidoc[tag=refresh-interval-default]
-indices that have received one search request or more in the last 30 seconds.
 This is the optimal configuration if you have no or very little search traffic
 (e.g. less than one search request every 5 minutes) and want to optimize for
 indexing speed. This behavior aims to automatically optimize bulk indexing in
@@ -55,7 +54,7 @@ On the other hand, if your index experiences regular search requests, this
 default behavior means that Elasticsearch will refresh your index every 1
 second. If you can afford to increase the amount of time between when a document
 gets indexed and when it becomes visible, increasing the
-<<dynamic-index-settings,`index.refresh_interval`>> to a larger value, e.g.
+<<index-refresh-interval-setting,`index.refresh_interval`>> to a larger value, e.g.
 `30s`, might help improve indexing speed.
 
 [float]

docs/reference/index-modules.asciidoc

@@ -106,6 +106,7 @@ specific index module:
     How long a shard can not receive a search or get request until it's considered
     search idle. (default is `30s`)
 
+[[index-refresh-interval-setting]]
 `index.refresh_interval`::
 
     How often to perform a refresh operation, which makes recent changes to the

docs/reference/indices/refresh.asciidoc

@@ -1,28 +1,103 @@
 [[indices-refresh]]
-=== Refresh
+=== Refresh API
+++++
+<titleabbrev>Refresh</titleabbrev>
+++++
 
-The refresh API allows to explicitly refresh one or more index, making
+Refreshes one or more indices.
-all operations performed since the last refresh available for search.
-The (near) real-time capabilities depend on the index engine used. For
-example, the internal one requires refresh to be called, but by default a
-refresh is scheduled periodically.
 
 [source,console]
---------------------------------------------------
+----
 POST /twitter/_refresh
---------------------------------------------------
+----
 // TEST[setup:twitter]
 
-[float]
-==== Multi Index
 
-The refresh API can be applied to more than one index with a single
+[[refresh-api-request]]
-call, or even on `_all` the indices.
+==== {api-request-title}
+
+`POST <index>/_refresh`
+
+`GET <index>/_refresh`
+
+`POST /_refresh`
+
+`GET /_refresh`
+
+
+[[refresh-api-desc]]
+==== {api-description-title}
+
+Use the refresh API to explicitly refresh one or more indices.
+A _refresh_ makes all operations performed on an index
+since the last refresh
+available for search.
+
+// tag::refresh-interval-default[]
+By default, Elasticsearch periodically refreshes indices every second, but only on
+indices that have received one search request or more in the last 30 seconds.
+// end::refresh-interval-default[]
+You can change this default interval
+using the <<index-refresh-interval-setting,`index.refresh_interval`>> setting.
+
+[IMPORTANT]
+====
+Refreshes are a resource-intensive.
+To ensure good cluster performance,
+we recommend waiting for {es}'s periodic refresh 
+rather than performing an explicit refresh
+when possible.
+
+If your application workflow
+indexes documents and then runs a search
+to retrieve the indexed document,
+we recommend using the <<docs-index_,index API>>'s
+`refresh=wait_for` query parameter option.
+This option ensures the indexing operation waits
+for a periodic refresh
+before running the search.
+====
+
+[[refresh-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
++
+To refresh all indices in the cluster,
+omit this parameter
+or use a value of `_all` or `*`.
+
+
+[[refresh-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+
+[[refresh-api-example]]
+==== {api-examples-title}
+
+
+[[refresh-api-multiple-ex]]
+===== Refresh several indices
 
 [source,console]
---------------------------------------------------
+----
 POST /kimchy,elasticsearch/_refresh
-
+----
-POST /_refresh
---------------------------------------------------
 // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
+
+
+[[refresh-api-all-ex]]
+===== Refresh all indices
+
+[source,console]
+----
+POST /_refresh
+----