[Backport 8.17] Add snapshot and restore examples (#3474)

specification/_doc_ids/table.csv

@@ -64,7 +64,6 @@ ccr-put-follow,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/
 ccr-resume-auto-follow-pattern,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ccr-resume-auto-follow-pattern.html
 ccs-network-delays,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#ccs-network-delays
 clean-up-snapshot-repo,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-cleanup
-clean-up-snapshot-repo-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clean-up-snapshot-repo-api.html
 clear-repositories-metering-archive-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-repositories-metering-archive-api.html
 clear-scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-scroll-api.html
 clear-sql-cursor-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html
@@ -654,7 +653,18 @@ slm-api-get-status,https://www.elastic.co/guide/en/elasticsearch/reference/{bran
 slm-api-put-policy,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-put-policy.html
 slm-api-start,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-start.html
 slm-api-stop,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-stop.html
+snapshot-clone,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clone-snapshot-api.html
 snapshot-create,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-take-snapshot.html
+snapshot-create-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/create-snapshot-api.html
+snapshot-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-snapshot-api.html
+snapshot-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-snapshot-api.html
+snapshot-restore-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/restore-snapshot-api.html
+snapshot-status,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-snapshot-status-api.html
+snapshot-repo-cleanup,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clean-up-snapshot-repo-api.html
+snapshot-repo-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-snapshot-repo-api.html
+snapshot-repo-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-snapshot-repo-api.html
+snapshot-repo-verify,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/verify-snapshot-repo-api.html
+snapshot-repo-verify-integrity,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/verify-repo-integrity-api.html
 sort-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-processor.html
 sort-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html
 sort-tiebreaker,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html#eql-search-specify-a-sort-tiebreaker

specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts

@@ -28,6 +28,7 @@ import { Duration } from '@_types/Time'
  * @availability stack since=7.4.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage
+ * @doc_id snapshot-repo-cleanup
  * @ext_doc_id clean-up-snapshot-repo
  */
 export interface Request extends RequestBase {

specification/snapshot/cleanup_repository/examples/response/SnapshotCleanupRepositoryResponseExample1.yaml

@@ -0,0 +1,7 @@
+# summary:
+description: A successful response from `POST /_snapshot/my_repository/_cleanup`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"results\": {\n    \"deleted_bytes\": 20,\n    \"deleted_blobs\": 5\n\
+  \  }\n}"

specification/snapshot/clone/SnapshotCloneRequest.ts

@@ -28,6 +28,7 @@ import { Duration } from '@_types/Time'
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage
+ * @doc_id snapshot-clone
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/snapshot/clone/examples/request/SnapshotCloneRequestExample1.yaml

@@ -0,0 +1,5 @@
+# summary:
+# method_request: PUT /_snapshot/my_repository/source_snapshot/_clone/target_snapshot
+description: Run `PUT /_snapshot/my_repository/source_snapshot/_clone/target_snapshot` to clone the `source_snapshot` into a new `target_snapshot`.
+# type: request
+value: "{\n  \"indices\": \"index_a,index_b\"\n}"

specification/snapshot/create/SnapshotCreateRequest.ts

@@ -28,6 +28,7 @@ import { Duration } from '@_types/Time'
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges create_snapshot
+ * @doc_id snapshot-create-api
  * @ext_doc_id snapshot-create
  */
 export interface Request extends RequestBase {

specification/snapshot/create/examples/request/SnapshotCreateRequestExample1.yaml

@@ -0,0 +1,8 @@
+# summary:
+# method_request: PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
+description: Run `PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true` to take a snapshot of `index_1` and `index_2`.
+# type: request
+value:
+  "{\n  \"indices\": \"index_1,index_2\",\n  \"ignore_unavailable\": true,\n\
+  \  \"include_global_state\": false,\n  \"metadata\": {\n    \"taken_by\": \"user123\"\
+  ,\n    \"taken_because\": \"backup before upgrading\"\n  }\n}"

specification/snapshot/create/examples/response/SnapshotCreateResponseExample1.yaml

@@ -0,0 +1,15 @@
+# summary:
+description: A successful response from `PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"snapshot\": {\n    \"snapshot\": \"snapshot_2\",\n    \"uuid\": \"\
+  vdRctLCxSketdKb54xw67g\",\n    \"repository\": \"my_repository\",\n    \"version_id\"\
+  : <version_id>,\n    \"version\": <version>,\n    \"indices\": [],\n    \"data_streams\"\
+  : [],\n    \"feature_states\": [],\n    \"include_global_state\": false,\n    \"\
+  metadata\": {\n      \"taken_by\": \"user123\",\n      \"taken_because\": \"backup\
+  \ before upgrading\"\n    },\n    \"state\": \"SUCCESS\",\n    \"start_time\": \"\
+  2020-06-25T14:00:28.850Z\",\n    \"start_time_in_millis\": 1593093628850,\n    \"\
+  end_time\": \"2020-06-25T14:00:28.850Z\",\n    \"end_time_in_millis\": 1593094752018,\n\
+  \    \"duration_in_millis\": 0,\n    \"failures\": [],\n    \"shards\": {\n    \
+  \  \"total\": 0,\n      \"failed\": 0,\n      \"successful\": 0\n    }\n  }\n}"

specification/snapshot/create_repository/examples/request/SnapshotCreateRepositoryRequestExample1.yaml

@@ -0,0 +1,7 @@
+summary: A shared file system repository
+# method_request: PUT /_snapshot/my_repository
+description: Run `PUT /_snapshot/my_repository` to create or update a shared file system snapshot repository.
+# type: request
+value:
+  "{\n  \"type\": \"fs\",\n  \"settings\": {\n    \"location\": \"my_backup_location\"\
+  \n  }\n}"

specification/snapshot/create_repository/examples/request/SnapshotCreateRepositoryRequestExample2.yaml

@@ -0,0 +1,7 @@
+summary: An Azure repository
+# method_request: PUT _snapshot/my_backup
+description: Run `PUT /_snapshot/my_repository` to create or update an Azure snapshot repository.
+# type: request
+value:
+  "{\n  \"type\": \"azure\",\n  \"settings\": {\n    \"client\": \"secondary\"\
+  \n  }\n}"