Update docs for Open/Close API (#43809)

Relates #43530

docs/reference/indices/open-close.asciidoc

@@ -2,23 +2,69 @@
 == Open / Close Index API
 
 The open and close index APIs allow to close an index, and later on
-opening it. A closed index has almost no overhead on the cluster (except
+opening it.
-for maintaining its metadata), and is blocked for read/write operations.
-A closed index can be opened which will then go through the normal
-recovery process.
 
-The REST endpoint is `/{index}/_close` and `/{index}/_open`. For
+A closed index is blocked for read/write operations and does not allow
-example:
+all operations that opened indices allow. It is not possible to index
+documents or to search for documents in a closed index. This allows
+closed indices to not have to maintain internal data structures for
+indexing or searching documents, resulting in a smaller overhead on
+the cluster.
+
+When opening or closing an index, the master is responsible for
+restarting the index shards to reflect the new state of the index.
+The shards will then go through the normal recovery process. The
+data of opened/closed indices is automatically replicated by the
+cluster to ensure that enough shard copies are safely kept around
+at all times.
+
+The REST endpoint is `/{index}/_close` and `/{index}/_open`.
+
+The following example shows how to close an index:
 
 [source,js]
 --------------------------------------------------
 POST /my_index/_close
-
-POST /my_index/_open
 --------------------------------------------------
 // CONSOLE
 // TEST[s/^/PUT my_index\n/]
 
+This will return the following response:
+
+[source,js]
+--------------------------------------------------
+{
+    "acknowledged" : true,
+    "shards_acknowledged" : true,
+    "indices" : {
+        "my_index" : {
+            "closed" : true
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+A closed index can be reopened like this:
+
+[source,js]
+--------------------------------------------------
+POST /my_index/_open
+--------------------------------------------------
+// CONSOLE
+// TEST[s/^/PUT my_index\nPOST my_index\/_close\n/]
+
+which will yield the following response:
+
+[source,js]
+--------------------------------------------------
+{
+    "acknowledged" : true,
+    "shards_acknowledged" : true
+}
+--------------------------------------------------
+// TESTRESPONSE
+
 It is possible to open and close multiple indices. An error will be thrown
 if the request explicitly refers to a missing index. This behaviour can be
 disabled using the `ignore_unavailable=true` parameter.
@@ -36,6 +82,6 @@ API by setting `cluster.indices.close.enable` to `false`. The default is `true`.
 [float]
 === Wait For Active Shards
 
-Because opening an index allocates its shards, the
+Because opening or closing an index allocates its shards, the
 <<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting on
-index creation applies to the index opening action as well.
+index creation applies to the `_open` and `_close` index actions as well.