From 2ac27de037f21286d1eb62757e9147edbfc3d67b Mon Sep 17 00:00:00 2001
From: lcawl <lcawley@elastic.co>
Date: Tue, 7 Jan 2025 18:32:57 -0800
Subject: [PATCH] Add search snapshot API examples

---
 output/openapi/elasticsearch-openapi.json     | 30 +++++++++----
 output/schema/schema.json                     | 44 ++++++++++++-------
 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, 133 insertions(+), 27 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 9fd5d02b8e..95f71ae17c 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -28252,6 +28252,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": [
           {
@@ -28273,6 +28276,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": [
           {
@@ -28297,6 +28303,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": [
           {
@@ -28324,6 +28333,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": [
           {
@@ -28359,7 +28371,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": {
@@ -28370,7 +28382,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": {
@@ -28381,7 +28393,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"
@@ -28391,7 +28403,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"
@@ -28401,7 +28413,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"
@@ -28422,12 +28434,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"
@@ -103870,7 +103884,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": {
@@ -103890,7 +103904,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": {
@@ -103931,7 +103945,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 60c8a5ec59..fec2cfac7f 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -15541,7 +15541,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": [
@@ -15583,7 +15586,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": [
@@ -15628,7 +15634,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": [
@@ -15670,7 +15677,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": [
@@ -190382,7 +190390,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": {
@@ -190407,7 +190415,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/cache_stats/Request.ts#L24-L38"
+      "specLocation": "searchable_snapshots/cache_stats/Request.ts#L24-L43"
     },
     {
       "kind": "response",
@@ -190563,7 +190571,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": {
@@ -190613,7 +190621,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts#L23-L40"
+      "specLocation": "searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts#L23-L46"
     },
     {
       "kind": "response",
@@ -190681,6 +190689,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": {
@@ -190692,6 +190701,7 @@
             }
           },
           {
+            "description": "The name of the index that will be created.",
             "name": "renamed_index",
             "required": false,
             "type": {
@@ -190703,6 +190713,7 @@
             }
           },
           {
+            "description": "The settings that should be added to the index when it is mounted.",
             "name": "index_settings",
             "required": false,
             "type": {
@@ -190721,6 +190732,7 @@
             }
           },
           {
+            "description": "The names of settings that should be removed from the index when it is mounted.",
             "name": "ignore_index_settings",
             "required": false,
             "type": {
@@ -190749,7 +190761,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": {
@@ -190761,7 +190773,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": {
@@ -190775,7 +190787,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",
@@ -190788,7 +190800,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,
@@ -190801,7 +190813,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",
@@ -190814,7 +190826,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts#L26-L55"
+      "specLocation": "searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts#L26-L86"
     },
     {
       "kind": "response",
@@ -190861,7 +190873,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": {
@@ -190887,7 +190899,7 @@
           }
         }
       ],
-      "specLocation": "searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts#L24-L38"
+      "specLocation": "searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts#L24-L42"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index 2dc98b5983..8720158cf3 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -588,7 +588,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 9a7487e4d9..21f8c3e751 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: {