From 054a6a4dd91bf9d114809cfc58236629fd557593 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Wed, 11 Dec 2024 10:09:33 -0800
Subject: [PATCH] [DOCS] Edit feature operation summaries (#3267)

(cherry picked from commit d56831ba3ee45a89dde89923187caa6d231fa877)
---
 output/openapi/elasticsearch-openapi.json       |  9 +++++++--
 output/schema/schema.json                       | 14 ++++++++------
 specification/_doc_ids/table.csv                |  1 +
 .../features/get_features/GetFeaturesRequest.ts | 11 +++++++++++
 .../reset_features/ResetFeaturesRequest.ts      | 17 +++++++++++++++++
 5 files changed, 44 insertions(+), 8 deletions(-)

diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index 03f56ed52e..5d41e57a3e 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -8235,7 +8235,11 @@
         "tags": [
           "features"
         ],
-        "summary": "Gets a list of features which can be included in snapshots using the feature_states field when creating a snapshot",
+        "summary": "Get the features",
+        "description": "Get a list of features that can be included in snapshots using the `feature_states` field when creating a snapshot.\nYou can use this API to determine which feature states to include when taking a snapshot.\nBy default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.\n\nA feature state includes one or more system indices necessary for a given feature to function.\nIn order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.\n\nThe features listed by this API are a combination of built-in features and features defined by plugins.\nIn order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-take-snapshot.html"
+        },
         "operationId": "features-get-features",
         "responses": {
           "200": {
@@ -8268,7 +8272,8 @@
         "tags": [
           "features"
         ],
-        "summary": "Resets the internal state of features, usually by deleting system indices",
+        "summary": "Reset the features",
+        "description": "Clear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.\n\nWARNING: Intended for development and testing use only. Do not reset features on a production cluster.\n\nReturn a cluster to the same state as a new installation by resetting the feature state for all Elasticsearch features.\nThis deletes all state information stored in system indices.\n\nThe response code is HTTP 200 if the state is successfully reset for all features.\nIt is HTTP 500 if the reset operation failed for any feature.\n\nNote that select features might provide a way to reset particular system indices.\nUsing this API resets all features, both those that are built-in and implemented as plugins.\n\nTo list the features that will be affected, use the get features API.\n\nIMPORTANT: The features installed on the node you submit this request to are the features that will be reset. Run on the master node if you have any doubts about which plugins are installed on individual nodes.",
         "operationId": "features-reset-features",
         "responses": {
           "200": {
diff --git a/output/schema/schema.json b/output/schema/schema.json
index cb320f12ca..c6444b98c3 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -4950,8 +4950,10 @@
           "stability": "stable"
         }
       },
-      "description": "Gets a list of features which can be included in snapshots using the feature_states field when creating a snapshot",
+      "description": "Get the features.\nGet a list of features that can be included in snapshots using the `feature_states` field when creating a snapshot.\nYou can use this API to determine which feature states to include when taking a snapshot.\nBy default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.\n\nA feature state includes one or more system indices necessary for a given feature to function.\nIn order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.\n\nThe features listed by this API are a combination of built-in features and features defined by plugins.\nIn order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-features-api.html",
+      "extDocId": "snapshot-create",
+      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-take-snapshot.html",
       "name": "features.get_features",
       "request": {
         "name": "Request",
@@ -4985,7 +4987,7 @@
           "stability": "experimental"
         }
       },
-      "description": "Resets the internal state of features, usually by deleting system indices",
+      "description": "Reset the features.\nClear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.\n\nWARNING: Intended for development and testing use only. Do not reset features on a production cluster.\n\nReturn a cluster to the same state as a new installation by resetting the feature state for all Elasticsearch features.\nThis deletes all state information stored in system indices.\n\nThe response code is HTTP 200 if the state is successfully reset for all features.\nIt is HTTP 500 if the reset operation failed for any feature.\n\nNote that select features might provide a way to reset particular system indices.\nUsing this API resets all features, both those that are built-in and implemented as plugins.\n\nTo list the features that will be affected, use the get features API.\n\nIMPORTANT: The features installed on the node you submit this request to are the features that will be reset. Run on the master node if you have any doubts about which plugins are installed on individual nodes.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html",
       "name": "features.reset_features",
       "request": {
@@ -118285,7 +118287,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Gets a list of features which can be included in snapshots using the feature_states field when creating a snapshot",
+      "description": "Get the features.\nGet a list of features that can be included in snapshots using the `feature_states` field when creating a snapshot.\nYou can use this API to determine which feature states to include when taking a snapshot.\nBy default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.\n\nA feature state includes one or more system indices necessary for a given feature to function.\nIn order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.\n\nThe features listed by this API are a combination of built-in features and features defined by plugins.\nIn order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -118298,7 +118300,7 @@
       },
       "path": [],
       "query": [],
-      "specLocation": "features/get_features/GetFeaturesRequest.ts#L22-L26"
+      "specLocation": "features/get_features/GetFeaturesRequest.ts#L22-L37"
     },
     {
       "kind": "response",
@@ -118335,7 +118337,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Resets the internal state of features, usually by deleting system indices",
+      "description": "Reset the features.\nClear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.\n\nWARNING: Intended for development and testing use only. Do not reset features on a production cluster.\n\nReturn a cluster to the same state as a new installation by resetting the feature state for all Elasticsearch features.\nThis deletes all state information stored in system indices.\n\nThe response code is HTTP 200 if the state is successfully reset for all features.\nIt is HTTP 500 if the reset operation failed for any feature.\n\nNote that select features might provide a way to reset particular system indices.\nUsing this API resets all features, both those that are built-in and implemented as plugins.\n\nTo list the features that will be affected, use the get features API.\n\nIMPORTANT: The features installed on the node you submit this request to are the features that will be reset. Run on the master node if you have any doubts about which plugins are installed on individual nodes.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -118348,7 +118350,7 @@
       },
       "path": [],
       "query": [],
-      "specLocation": "features/reset_features/ResetFeaturesRequest.ts#L22-L27"
+      "specLocation": "features/reset_features/ResetFeaturesRequest.ts#L22-L44"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index bd36f9b239..c01ef661ba 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -597,6 +597,7 @@ 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-create,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-take-snapshot.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
diff --git a/specification/features/get_features/GetFeaturesRequest.ts b/specification/features/get_features/GetFeaturesRequest.ts
index 6ce3930724..533c11229b 100644
--- a/specification/features/get_features/GetFeaturesRequest.ts
+++ b/specification/features/get_features/GetFeaturesRequest.ts
@@ -20,7 +20,18 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Get the features.
+ * Get a list of features that can be included in snapshots using the `feature_states` field when creating a snapshot.
+ * You can use this API to determine which feature states to include when taking a snapshot.
+ * By default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.
+ *
+ * A feature state includes one or more system indices necessary for a given feature to function.
+ * In order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.
+ *
+ * The features listed by this API are a combination of built-in features and features defined by plugins.
+ * In order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.
  * @rest_spec_name features.get_features
  * @availability stack since=7.12.0 stability=stable
+ * @ext_doc_id snapshot-create
  */
 export interface Request extends RequestBase {}
diff --git a/specification/features/reset_features/ResetFeaturesRequest.ts b/specification/features/reset_features/ResetFeaturesRequest.ts
index 57911fb39d..4364a55ccf 100644
--- a/specification/features/reset_features/ResetFeaturesRequest.ts
+++ b/specification/features/reset_features/ResetFeaturesRequest.ts
@@ -20,6 +20,23 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Reset the features.
+ * Clear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.
+ *
+ * WARNING: Intended for development and testing use only. Do not reset features on a production cluster.
+ *
+ * Return a cluster to the same state as a new installation by resetting the feature state for all Elasticsearch features.
+ * This deletes all state information stored in system indices.
+ *
+ * The response code is HTTP 200 if the state is successfully reset for all features.
+ * It is HTTP 500 if the reset operation failed for any feature.
+ *
+ * Note that select features might provide a way to reset particular system indices.
+ * Using this API resets all features, both those that are built-in and implemented as plugins.
+ *
+ * To list the features that will be affected, use the get features API.
+ *
+ * IMPORTANT: The features installed on the node you submit this request to are the features that will be reset. Run on the master node if you have any doubts about which plugins are installed on individual nodes.
  * @rest_spec_name features.reset_features
  * @availability stack since=7.12.0 stability=experimental
  * @availability serverless stability=experimental visibility=private