Add additional technical writer feedback to Cluster APIs (#824)

Signed-off-by: Archer <[email protected]>
Signed-off-by: Naarcha-AWS <[email protected]>

Author: Naarcha-AWS

CHANGELOG.md

@@ -5,6 +5,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
+- Added defaults for Cluster APIs ([#824](https://github.com/opensearch-project/opensearch-api-specification/pull/824/))
 - Added `aggs` alias for nested aggregations ([#818](https://github.com/opensearch-project/opensearch-api-specification/pull/818))
 - Added API specs for query groups lifecycle APIs ([#649](https://github.com/opensearch-project/opensearch-api-specification/pull/649))
 - Added Python and Ruby spec validators ([#646](https://github.com/opensearch-project/opensearch-api-specification/pull/646))

spec/namespaces/cluster.yaml

@@ -834,7 +834,7 @@ components:
     cluster.allocation_explain::query.include_yes_decisions:
       in: query
       name: include_yes_decisions
-      description: When `true`, returns any `YES` decisions in the allocation explanation.
+      description: When `true`, returns any `YES` decisions in the allocation explanation. `YES` decisions indicate when a particular shard allocation attempt was successful for the given node.
       schema:
         type: boolean
         default: false
@@ -852,7 +852,7 @@ components:
     cluster.delete_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
-      description: Operation timeout for connection to cluster-manager node.
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       x-version-added: '2.0'
@@ -897,6 +897,7 @@ components:
       style: simple
     cluster.exists_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -932,14 +933,18 @@ components:
       style: simple
     cluster.get_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
+        default: 30s
       x-version-added: '2.0'
     cluster.get_component_template::query.flat_settings:
       in: query
       name: flat_settings
-      description: If `true`, returns settings in flat format.
+      description: |- 
+        Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings.
+        For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`.
       schema:
         type: boolean
         default: false
@@ -973,6 +978,7 @@ components:
       required: true
     cluster.get_settings::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1033,6 +1039,7 @@ components:
     cluster.health::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       x-version-added: '2.0'
@@ -1041,6 +1048,7 @@ components:
       name: expand_wildcards
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/ExpandWildcards'
+        default: open
       style: form
     cluster.health::query.level:
       in: query
@@ -1069,13 +1077,15 @@ components:
     cluster.health::query.timeout:
       in: query
       name: timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       style: form
     cluster.health::query.wait_for_active_shards:
       in: query
       name: wait_for_active_shards
       schema:
+        default: 0
         $ref: '../schemas/_common.yaml#/components/schemas/WaitForActiveShards'
       style: form
     cluster.health::query.wait_for_events:
@@ -1098,6 +1108,7 @@ components:
       description: Whether to wait until there are no relocating shards in the cluster.
       schema:
         type: boolean
+        default: false
       style: form
     cluster.health::query.wait_for_nodes:
       in: query
@@ -1117,6 +1128,7 @@ components:
       style: form
     cluster.pending_tasks::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1184,6 +1196,7 @@ components:
       style: simple
     cluster.put_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1221,13 +1234,14 @@ components:
     cluster.put_decommission_awareness::path.awareness_attribute_value:
       name: awareness_attribute_value
       in: path
-      description: The value of the awareness attribute.
+      description: The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method.
       schema:
         type: string
-        description: The value of the awareness attribute.
+        description: The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method.
       required: true
     cluster.put_settings::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1258,14 +1272,15 @@ components:
     cluster.put_weighted_routing::path.attribute:
       name: attribute
       in: path
-      description: The name of the awareness attribute.
+      description: The name of awareness attribute, usually `zone`.
       schema:
         type: string
-        description: The name of the awareness attribute.
+        description: The name of awareness attribute, usually `zone`.
       required: true
     cluster.reroute::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       x-version-added: '2.0'
@@ -1279,7 +1294,7 @@ components:
     cluster.reroute::query.explain:
       in: query
       name: explain
-      description: When `true`, the response contains an explanation of why certain commands can or cannot be executed.
+      description: When `true`, the response contains an explanation of why reroute certain commands can or cannot be executed.
       schema:
         type: boolean
       style: form
@@ -1342,6 +1357,7 @@ components:
       style: form
     cluster.state::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'

spec/schemas/_common.yaml

@@ -1054,14 +1054,25 @@ components:
         - shards
     WaitForEvents:
       description: Waits until all currently queued events with the given priority are processed. 
-      type: string
-      enum:
-        - high
-        - immediate
-        - languid
-        - low
-        - normal
-        - urgent
+      oneOf:
+        - type: string
+          const: immediate
+          description: Highest priority, processed as soon as possible.
+        - type: string
+          const: urgent
+          description: Very high priority, processed after immediate events.
+        - type: string
+          const: high
+          description: High priority, processed after urgent events.
+        - type: string
+          const: normal
+          description: Default priority, processed after high priority events.
+        - type: string
+          const: low
+          description: Low priority, processed after normal events.
+        - type: string
+          const: languid
+          description: Lowest priority, processed after all other events.
     DataStreamName:
       type: string
     CompletionStats:

spec/schemas/cluster.reroute.yaml

@@ -121,17 +121,34 @@ components:
         - node
         - shard
     Metric:
-      type: string
-      enum:
-        - _all
-        - blocks
-        - cluster_manager_node
-        - master_node
-        - metadata
-        - nodes
-        - routing_nodes
-        - routing_table
-        - version
+      oneOf:
+        - type: string
+          const: _all
+          description: Returns all available metrics.
+        - type: string
+          const: blocks
+          description: Returns information about cluster-level blocks.
+        - type: string
+          const: cluster_manager_node
+          description: Returns information about the current cluster manager node.
+        - type: string
+          const: master_node
+          description: The alias for `cluster_manager_node`. Deprecated, but maintained for backwards compatibility.
+        - type: string
+          const: metadata
+          description: Returns the cluster state metadata.
+        - type: string
+          const: nodes
+          description: Returns information about nodes in the cluster.
+        - type: string
+          const: routing_nodes
+          description: Returns the node-level shard allocations.
+        - type: string
+          const: routing_table
+          description: Returns index-level shard allocations.
+        - type: string
+          const: version
+          description: Returns the cluster state version.
     RerouteExplanation:
       type: object
       properties: