[OpenAPI] Edits the autoscaling APIs (#3081)

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

Author: lcawl

docs/overlays/elasticsearch-openapi-overlays.yaml

@@ -267,4 +267,52 @@ actions:
               examples:
                 indicesOpenResponseExample1:
                   $ref: "../../specification/indices/open/indicesOpenResponseExample1.yaml"
-
+  - target: "$.paths['/_autoscaling/policy/{name}']['delete']"
+    description: "Add examples for delete autoscaling policy response"
+    update:
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                deleteAutoscalingPolicyResponseExample1:
+                  $ref: "../../specification/autoscaling/delete_autoscaling_policy/autoscalingApisDeleteAutoscalingPolicyResponseExample1.yaml"
+  - target: "$.paths['/_autoscaling/capacity']['get']"
+    description: "Add examples for get autoscaling capacity response"
+    update:
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                getAutoscalingCapacityResponseExample1:
+                  $ref: "../../specification/autoscaling/get_autoscaling_capacity/autoscalingApisGetAutoscalingCapacityResponseExample1.yaml"
+  - target: "$.paths['/_autoscaling/policy/{name}']['get']"
+    description: "Add examples for get autoscaling policy response"
+    update:
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                getAutoscalingPolicyResponseExample1:
+                  $ref: "../../specification/autoscaling/get_autoscaling_policy/autoscalingApisGetAutoscalingPolicyResponseExample1.yaml"
+  - target: "$.paths['/_autoscaling/policy/{name}']['put']"
+    description: "Add examples for create autoscaling policy operation"
+    update:
+      update: 
+      requestBody: 
+        content: 
+          application/json: 
+            examples:
+              createAutoscalingPolicyRequestExample1: 
+                $ref: "../../specification/autoscaling/put_autoscaling_policy/autoscalingApisPutAutoscalingPolicyRequestExample1.yaml"
+              createAutoscalingPolicyRequestExample2: 
+                $ref: "../../specification/autoscaling/put_autoscaling_policy/autoscalingApisPutAutoscalingPolicyRequestExample2.yaml"
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                createAutoscalingPolicyResponseExample1:
+                  $ref: "../../specification/autoscaling/put_autoscaling_policy/autoscalingApisPutAutoscalingPolicyResponseExample1.yaml"

output/openapi/elasticsearch-openapi.json

@@ -10,6 +10,8 @@ api-date-math-index-names,https://www.elastic.co/guide/en/elasticsearch/referenc
 append-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/append-processor.html
 async-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/async-search.html
 attachment,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/attachment.html
+autoscaling,https://www.elastic.co/guide/en/cloud/current/ec-autoscaling.html
+autoscaling-deciders,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/autoscaling-deciders.html
 autoscaling-delete-autoscaling-policy,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/autoscaling-delete-autoscaling-policy.html
 autoscaling-get-autoscaling-capacity,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/autoscaling-get-autoscaling-capacity.html
 autoscaling-get-autoscaling-policy,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/autoscaling-get-autoscaling-policy.html

output/schema/schema.json

@@ -22,6 +22,9 @@ import { UserDefinedValue } from '@spec_utils/UserDefinedValue'
 
 export class AutoscalingPolicy {
   roles: string[]
-  /** Decider settings */
+  /**
+   * Decider settings.
+   * @ext_doc_id autoscaling-deciders
+   */
   deciders: Dictionary<string, UserDefinedValue>
 }

specification/_doc_ids/table.csv

@@ -21,9 +21,13 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Delete an autoscaling policy.
+ *
+ * NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
  * @rest_spec_name autoscaling.delete_autoscaling_policy
  * @availability stack since=7.11.0 stability=stable
  * @doc_id autoscaling-delete-autoscaling-policy
+ * @ext_doc_id autoscaling
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/autoscaling/_types/AutoscalingPolicy.ts

@@ -0,0 +1,6 @@
+summary: A successful response of deleting one or more autoscaling policy.
+description: >
+  This may be a response to either `DELETE /_autoscaling/policy/my_autoscaling_policy` or `DELETE /_autoscaling/policy/*`.
+# type: "response"
+# response_code: 200
+value: "{\n  \"acknowledged\": true\n}"

specification/autoscaling/delete_autoscaling_policy/DeleteAutoscalingPolicyRequest.ts

@@ -20,8 +20,23 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Get the autoscaling capacity.
+ *
+ * NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
+ *
+ * This API gets the current autoscaling capacity based on the configured autoscaling policy.
+ * It will return information to size the cluster appropriately to the current workload.
+ *
+ * The `required_capacity` is calculated as the maximum of the `required_capacity` result of all individual deciders that are enabled for the policy.
+ *
+ * The operator should verify that the `current_nodes` match the operator’s knowledge of the cluster to avoid making autoscaling decisions based on stale or incomplete information.
+ *
+ * The response contains decider-specific information you can use to diagnose how and why autoscaling determined a certain capacity was required.
+ * This information is provided for diagnosis only.
+ * Do not use this information to make autoscaling decisions.
  * @rest_spec_name autoscaling.get_autoscaling_capacity
  * @availability stack since=7.11.0 stability=stable
  * @doc_id autoscaling-get-autoscaling-capacity
+ * @ext_doc_id autoscaling
  */
 export interface Request extends RequestBase {}

specification/autoscaling/delete_autoscaling_policy/autoscalingApisDeleteAutoscalingPolicyResponseExample1.json

@@ -0,0 +1,5 @@
+summary: 'A successful response for retrieving the current autoscaling capacity.'
+description: 'This may be a response to `GET /_autoscaling/capacity`.'
+# type: "response"
+# response_code: 200
+value: "{\n  policies: {}\n}"

specification/autoscaling/delete_autoscaling_policy/autoscalingApisDeleteAutoscalingPolicyResponseExample1.yaml

@@ -21,9 +21,13 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Get an autoscaling policy.
+ *
+ * NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
  * @rest_spec_name autoscaling.get_autoscaling_policy
  * @availability stack since=7.11.0 stability=stable
  * @doc_id autoscaling-get-autoscaling-capacity
+ * @ext_doc_id autoscaling
  */
 export interface Request extends RequestBase {
   path_parts: {