From 398cd43981dbe604fc63d17f5010b2ecc1d8ffc7 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Wed, 8 Jan 2025 10:38:38 -0800
Subject: [PATCH] Add search snapshot API examples (#3459)

(cherry picked from commit fd32ef05ff46091c0a91be83866f2430b2e6229d)
---
 output/openapi/elasticsearch-openapi.json     | 30 ++++++++----
 output/schema/schema.json                     | 46 ++++++++++++-------
 specification/_doc_ids/table.csv              |  4 ++
 .../cache_stats/Request.ts                    |  5 ++
 .../examples/response/ResponseExample1.yaml   | 21 +++++++++
 .../SearchableSnapshotsClearCacheRequest.ts   |  6 +++
 .../mount/SearchableSnapshotsMountRequest.ts  | 37 +++++++++++++--
 ...SnapshotsMountSnapshotRequestExample1.yaml |  9 ++++
 .../stats/SearchableSnapshotsStatsRequest.ts  |  4 ++
 9 files changed, 134 insertions(+), 28 deletions(-)
 create mode 100644 specification/searchable_snapshots/cache_stats/examples/response/ResponseExample1.yaml
 create mode 100644 specification/searchable_snapshots/mount/examples/request/SearchableSnapshotsMountSnapshotRequestExample1.yaml

diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index 585e3cb86a..1ecf1757fd 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -28042,6 +28042,9 @@
         ],
         "summary": "Get cache statistics",
         "description": "Get statistics about the shared cache for partially mounted indices.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html"
+        },
         "operationId": "searchable-snapshots-cache-stats",
         "parameters": [
           {
@@ -28063,6 +28066,9 @@
         ],
         "summary": "Get cache statistics",
         "description": "Get statistics about the shared cache for partially mounted indices.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html"
+        },
         "operationId": "searchable-snapshots-cache-stats-1",
         "parameters": [
           {
@@ -28087,6 +28093,9 @@
         ],
         "summary": "Clear the cache",
         "description": "Clear indices and data streams from the shared cache for partially mounted indices.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html"
+        },
         "operationId": "searchable-snapshots-clear-cache",
         "parameters": [
           {
@@ -28120,6 +28129,9 @@
         ],
         "summary": "Clear the cache",
         "description": "Clear indices and data streams from the shared cache for partially mounted indices.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html"
+        },
         "operationId": "searchable-snapshots-clear-cache-1",
         "parameters": [
           {
@@ -28161,7 +28173,7 @@
           {
             "in": "path",
             "name": "repository",
-            "description": "The name of the repository containing the snapshot of the index to mount",
+            "description": "The name of the repository containing the snapshot of the index to mount.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -28172,7 +28184,7 @@
           {
             "in": "path",
             "name": "snapshot",
-            "description": "The name of the snapshot of the index to mount",
+            "description": "The name of the snapshot of the index to mount.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -28183,7 +28195,7 @@
           {
             "in": "query",
             "name": "master_timeout",
-            "description": "Explicit operation timeout for connection to master node",
+            "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.",
             "deprecated": false,
             "schema": {
               "$ref": "#/components/schemas/_types:Duration"
@@ -28193,7 +28205,7 @@
           {
             "in": "query",
             "name": "wait_for_completion",
-            "description": "Should this request wait until the operation has completed before returning",
+            "description": "If true, the request blocks until the operation is complete.",
             "deprecated": false,
             "schema": {
               "type": "boolean"
@@ -28203,7 +28215,7 @@
           {
             "in": "query",
             "name": "storage",
-            "description": "Selects the kind of local storage used to accelerate searches. Experimental, and defaults to `full_copy`",
+            "description": "The mount option for the searchable snapshot index.",
             "deprecated": false,
             "schema": {
               "type": "string"
@@ -28224,12 +28236,14 @@
                     "$ref": "#/components/schemas/_types:IndexName"
                   },
                   "index_settings": {
+                    "description": "The settings that should be added to the index when it is mounted.",
                     "type": "object",
                     "additionalProperties": {
                       "type": "object"
                     }
                   },
                   "ignore_index_settings": {
+                    "description": "The names of settings that should be removed from the index when it is mounted.",
                     "type": "array",
                     "items": {
                       "type": "string"
@@ -103640,7 +103654,7 @@
       "searchable_snapshots.cache_stats#node_id": {
         "in": "path",
         "name": "node_id",
-        "description": "A comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes",
+        "description": "The names of the nodes in the cluster to target.",
         "required": true,
         "deprecated": false,
         "schema": {
@@ -103660,7 +103674,7 @@
       "searchable_snapshots.clear_cache#index": {
         "in": "path",
         "name": "index",
-        "description": "A comma-separated list of index names",
+        "description": "A comma-separated list of data streams, indices, and aliases to clear from the cache.\nIt supports wildcards (`*`).",
         "required": true,
         "deprecated": false,
         "schema": {
@@ -103719,7 +103733,7 @@
       "searchable_snapshots.stats#index": {
         "in": "path",
         "name": "index",
-        "description": "A comma-separated list of index names",
+        "description": "A comma-separated list of data streams and indices to retrieve statistics for.",
         "required": true,
         "deprecated": false,
         "schema": {
diff --git a/output/schema/schema.json b/output/schema/schema.json
index f34724898b..b749f60ba4 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -15559,7 +15559,10 @@
         }
       },
       "description": "Get cache statistics.\nGet statistics about the shared cache for partially mounted indices.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-apis.html",
+      "docId": "searchable-snapshots-api-cache-stats",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-cache-stats.html",
+      "extDocId": "searchable-snapshots",
+      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots.html",
       "name": "searchable_snapshots.cache_stats",
       "privileges": {
         "cluster": [
@@ -15601,7 +15604,10 @@
         }
       },
       "description": "Clear the cache.\nClear indices and data streams from the shared cache for partially mounted indices.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-apis.html",
+      "docId": "searchable-snapshots-api-clear-cache",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-clear-cache.html",
+      "extDocId": "searchable-snapshots",
+      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots.html",
       "name": "searchable_snapshots.clear_cache",
       "privileges": {
         "cluster": [
@@ -15646,7 +15652,8 @@
         }
       },
       "description": "Mount a snapshot.\nMount a snapshot as a searchable snapshot index.\nDo not use this API for snapshots managed by index lifecycle management (ILM).\nManually mounting ILM-managed snapshots can interfere with ILM processes.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-api-mount-snapshot.html",
+      "docId": "searchable-snapshots-api-mount-snapshot",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-mount-snapshot.html",
       "name": "searchable_snapshots.mount",
       "privileges": {
         "cluster": [
@@ -15688,7 +15695,8 @@
         }
       },
       "description": "Get searchable snapshot statistics.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-apis.html",
+      "docId": "searchable-snapshots-api-stats",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-stats.html",
       "name": "searchable_snapshots.stats",
       "privileges": {
         "cluster": [
@@ -190027,7 +190035,7 @@
       },
       "path": [
         {
-          "description": "A comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes",
+          "description": "The names of the nodes in the cluster to target.",
           "name": "node_id",
           "required": false,
           "type": {
@@ -190052,7 +190060,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/cache_stats/Request.ts#L24-L38"
+      "specLocation": "searchable_snapshots/cache_stats/Request.ts#L24-L43"
     },
     {
       "kind": "response",
@@ -190208,7 +190216,7 @@
       },
       "path": [
         {
-          "description": "A comma-separated list of index names",
+          "description": "A comma-separated list of data streams, indices, and aliases to clear from the cache.\nIt supports wildcards (`*`).",
           "name": "index",
           "required": false,
           "type": {
@@ -190280,7 +190288,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts#L23-L42"
+      "specLocation": "searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts#L23-L48"
     },
     {
       "kind": "response",
@@ -190348,6 +190356,7 @@
         "kind": "properties",
         "properties": [
           {
+            "description": "The name of the index contained in the snapshot whose data is to be mounted.\nIf no `renamed_index` is specified, this name will also be used to create the new index.",
             "name": "index",
             "required": true,
             "type": {
@@ -190359,6 +190368,7 @@
             }
           },
           {
+            "description": "The name of the index that will be created.",
             "name": "renamed_index",
             "required": false,
             "type": {
@@ -190370,6 +190380,7 @@
             }
           },
           {
+            "description": "The settings that should be added to the index when it is mounted.",
             "name": "index_settings",
             "required": false,
             "type": {
@@ -190388,6 +190399,7 @@
             }
           },
           {
+            "description": "The names of settings that should be removed from the index when it is mounted.",
             "name": "ignore_index_settings",
             "required": false,
             "type": {
@@ -190416,7 +190428,7 @@
       },
       "path": [
         {
-          "description": "The name of the repository containing the snapshot of the index to mount",
+          "description": "The name of the repository containing the snapshot of the index to mount.",
           "name": "repository",
           "required": true,
           "type": {
@@ -190428,7 +190440,7 @@
           }
         },
         {
-          "description": "The name of the snapshot of the index to mount",
+          "description": "The name of the snapshot of the index to mount.",
           "name": "snapshot",
           "required": true,
           "type": {
@@ -190442,7 +190454,7 @@
       ],
       "query": [
         {
-          "description": "Explicit operation timeout for connection to master node",
+          "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.",
           "name": "master_timeout",
           "required": false,
           "serverDefault": "30s",
@@ -190455,7 +190467,7 @@
           }
         },
         {
-          "description": "Should this request wait until the operation has completed before returning",
+          "description": "If true, the request blocks until the operation is complete.",
           "name": "wait_for_completion",
           "required": false,
           "serverDefault": false,
@@ -190468,7 +190480,7 @@
           }
         },
         {
-          "description": "Selects the kind of local storage used to accelerate searches. Experimental, and defaults to `full_copy`",
+          "description": "The mount option for the searchable snapshot index.",
           "name": "storage",
           "required": false,
           "serverDefault": "full_copy",
@@ -190481,7 +190493,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts#L26-L55"
+      "specLocation": "searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts#L26-L86"
     },
     {
       "kind": "response",
@@ -190528,7 +190540,7 @@
       },
       "path": [
         {
-          "description": "A comma-separated list of index names",
+          "description": "A comma-separated list of data streams and indices to retrieve statistics for.",
           "name": "index",
           "required": false,
           "type": {
@@ -190554,7 +190566,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts#L24-L38"
+      "specLocation": "searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts#L24-L42"
     },
     {
       "kind": "response",
@@ -207032,7 +207044,7 @@
           }
         }
       ],
-      "specLocation": "snapshot/clone/SnapshotCloneRequest.ts#L24-L45"
+      "specLocation": "snapshot/clone/SnapshotCloneRequest.ts#L24-L46"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index 1cd571caf5..4350c00333 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -589,7 +589,11 @@ search-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}
 search-terms-enum,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-terms-enum.html
 search-validate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-validate.html
 search-vector-tile-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-vector-tile-api.html
+searchable-snapshots,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots.html
+searchable-snapshots-api-cache-stats,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-cache-stats.html
+searchable-snapshots-api-clear-cache,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-clear-cache.html
 searchable-snapshots-api-mount-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-mount-snapshot.html
+searchable-snapshots-api-stats,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-stats.html
 searchable-snapshots-apis,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-apis.html
 search-templates,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html
 secure-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/secure-settings.html
diff --git a/specification/searchable_snapshots/cache_stats/Request.ts b/specification/searchable_snapshots/cache_stats/Request.ts
index 7ef9bc1781..42373b8f08 100644
--- a/specification/searchable_snapshots/cache_stats/Request.ts
+++ b/specification/searchable_snapshots/cache_stats/Request.ts
@@ -27,9 +27,14 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name searchable_snapshots.cache_stats
  * @availability stack since=7.13.0 stability=experimental
  * @cluster_privileges manage
+ * @doc_id searchable-snapshots-api-cache-stats
+ * @ext_doc_id searchable-snapshots
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The names of the nodes in the cluster to target.
+     */
     node_id?: NodeIds
   }
   query_parameters: {
diff --git a/specification/searchable_snapshots/cache_stats/examples/response/ResponseExample1.yaml b/specification/searchable_snapshots/cache_stats/examples/response/ResponseExample1.yaml
new file mode 100644
index 0000000000..fac5613207
--- /dev/null
+++ b/specification/searchable_snapshots/cache_stats/examples/response/ResponseExample1.yaml
@@ -0,0 +1,21 @@
+# summary:
+description: A successful response from `GET /_searchable_snapshots/cache/stats`.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "nodes" : {
+      "eerrtBMtQEisohZzxBLUSw" : {
+        "shared_cache" : {
+          "reads" : 6051,
+          "bytes_read_in_bytes" : 5448829,
+          "writes" : 37,
+          "bytes_written_in_bytes" : 1208320,
+          "evictions" : 5,
+          "num_regions" : 65536,
+          "size_in_bytes" : 1099511627776,
+          "region_size_in_bytes" : 16777216
+        }
+      }
+    }
+  }
diff --git a/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts b/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts
index 5c50a67828..d014ca76d5 100644
--- a/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts
+++ b/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts
@@ -27,9 +27,15 @@ import { ExpandWildcards, Indices } from '@_types/common'
  * @availability stack since=7.10.0 stability=experimental
  * @cluster_privileges manage
  * @index_privileges manage
+ * @doc_id searchable-snapshots-api-clear-cache
+ * @ext_doc_id searchable-snapshots
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * A comma-separated list of data streams, indices, and aliases to clear from the cache.
+     * It supports wildcards (`*`).
+     */
     index?: Indices
   }
   query_parameters: {
diff --git a/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts b/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts
index fcc880e756..c7430d968b 100644
--- a/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts
+++ b/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts
@@ -32,24 +32,55 @@ import { Duration } from '@_types/Time'
  * @availability stack since=7.10.0 stability=stable
  * @cluster_privileges manage
  * @index_privileges manage
+ * @doc_id searchable-snapshots-api-mount-snapshot
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The name of the repository containing the snapshot of the index to mount.
+     */
     repository: Name
+    /**
+     * The name of the snapshot of the index to mount.
+     */
     snapshot: Name
   }
   query_parameters: {
-    /** @server_default 30s */
+    /**
+     * The period to wait for the master node.
+     * If the master node is not available before the timeout expires, the request fails and returns an error.
+     * To indicate that the request should never timeout, set it to `-1`.
+     * @server_default 30s
+     */
     master_timeout?: Duration
-    /** @server_default false */
+    /**
+     * If true, the request blocks until the operation is complete.
+     * @server_default false
+     */
     wait_for_completion?: boolean
-    /** @server_default full_copy */
+    /**
+     * The mount option for the searchable snapshot index.
+     * @server_default full_copy
+     */
     storage?: string
   }
   body: {
+    /**
+     * The name of the index contained in the snapshot whose data is to be mounted.
+     * If no `renamed_index` is specified, this name will also be used to create the new index.
+     */
     index: IndexName
+    /**
+     * The name of the index that will be created.
+     */
     renamed_index?: IndexName
+    /**
+     * The settings that should be added to the index when it is mounted.
+     */
     index_settings?: Dictionary<string, UserDefinedValue>
+    /**
+     * The names of settings that should be removed from the index when it is mounted.
+     */
     ignore_index_settings?: string[]
   }
 }
diff --git a/specification/searchable_snapshots/mount/examples/request/SearchableSnapshotsMountSnapshotRequestExample1.yaml b/specification/searchable_snapshots/mount/examples/request/SearchableSnapshotsMountSnapshotRequestExample1.yaml
new file mode 100644
index 0000000000..7d38f8fc67
--- /dev/null
+++ b/specification/searchable_snapshots/mount/examples/request/SearchableSnapshotsMountSnapshotRequestExample1.yaml
@@ -0,0 +1,9 @@
+summary:
+# method_request: POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true
+description: >
+  Run `POST /_snapshot/my_repository/my_snapshot/_mount?wait_for_completion=true` to mount the index `my_docs` from an existing snapshot named `my_snapshot` stored in `my_repository` as a new index `docs`.
+# type: request
+value:
+  "{\n  \"index\": \"my_docs\",\n  \"renamed_index\": \"docs\",\n  \"index_settings\"\
+  : {\n    \"index.number_of_replicas\": 0\n  },\n  \"ignore_index_settings\": [ \"\
+  index.refresh_interval\" ]\n}"
diff --git a/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts b/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts
index 872a7c71c7..5fa9382611 100644
--- a/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts
+++ b/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts
@@ -27,9 +27,13 @@ import { StatsLevel } from '../_types/stats'
  * @availability stack since=7.10.0 stability=stable
  * @cluster_privileges manage
  * @index_privileges manage
+ * @doc_id searchable-snapshots-api-stats
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * A comma-separated list of data streams and indices to retrieve statistics for.
+     */
     index?: Indices
   }
   query_parameters: {