Add spec for cluster stats metric and index_metric filter paths.

Signed-off-by: Swetha Guptha <gupthasg@amazon.com>

Author: Swetha Guptha

CHANGELOG.md

@@ -129,6 +129,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added API spec for `adjust_pure_negative` for bool queries ([#641](https://github.com/opensearch-project/opensearch-api-specification/pull/641))
 - Added a spec style checker [#620](https://github.com/opensearch-project/opensearch-api-specification/pull/620).
 - Added `remote_store` to node `Stats` ([#643](https://github.com/opensearch-project/opensearch-api-specification/pull/643))
+- Added spec for _cluster/stats metric and index_metric filter paths([#639](https://github.com/opensearch-project/opensearch-api-specification/pull/639))
+
 
 ### Changed
 

spec/namespaces/cluster.yaml

@@ -331,6 +331,39 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/cluster.stats@200'
+  /_cluster/stats/{metric}/nodes/{node_id}:
+    get:
+      operationId: cluster.stats.2
+      x-operation-group: cluster.stats
+      x-version-added: '2.18'
+      description: Returns high-level overview of cluster statistics.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/
+      parameters:
+        - $ref: '#/components/parameters/cluster.stats::path.metric'
+        - $ref: '#/components/parameters/cluster.stats::path.node_id'
+        - $ref: '#/components/parameters/cluster.stats::query.flat_settings'
+        - $ref: '#/components/parameters/cluster.stats::query.timeout'
+      responses:
+        '200':
+          $ref: '#/components/responses/cluster.stats@200'
+  /_cluster/stats/{metric}/{index_metric}/nodes/{node_id}:
+    get:
+      operationId: cluster.stats.3
+      x-operation-group: cluster.stats
+      x-version-added: '2.18'
+      description: Returns high-level overview of cluster statistics.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/
+      parameters:
+        - $ref: '#/components/parameters/cluster.stats::path.index_metric'
+        - $ref: '#/components/parameters/cluster.stats::path.metric'
+        - $ref: '#/components/parameters/cluster.stats::path.node_id'
+        - $ref: '#/components/parameters/cluster.stats::query.flat_settings'
+        - $ref: '#/components/parameters/cluster.stats::query.timeout'
+      responses:
+        '200':
+          $ref: '#/components/responses/cluster.stats@200'
   /_cluster/voting_config_exclusions:
     post:
       operationId: cluster.post_voting_config_exclusions.0
@@ -1380,6 +1413,27 @@ components:
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       style: form
+    cluster.stats::path.index_metric:
+      in: path
+      name: index_metric
+      description: Limit the information returned for indices metric to the specific index metrics. It can be used only if indices (or all) metric is specified.
+      required: true
+      schema:
+        type: array
+        items:
+          $ref: '../schemas/cluster.stats.yaml#/components/schemas/IndexMetric'
+      style: simple
+    cluster.stats::path.metric:
+      in: path
+      name: metric
+      description: Limit the information returned to the specified metrics
+      required: true
+      schema:
+        type: array
+        items:
+          $ref: '../schemas/cluster.stats.yaml#/components/schemas/Metric'
+      style:
+        simple
     cluster.stats::path.node_id:
       in: path
       name: node_id

spec/schemas/cluster.stats.yaml

@@ -27,8 +27,6 @@ components:
           required:
             - cluster_name
             - cluster_uuid
-            - indices
-            - nodes
             - status
             - timestamp
     ClusterIndices:
@@ -60,17 +58,7 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/IndicesVersions'
-      required:
-        - analysis
-        - completion
-        - count
-        - docs
-        - fielddata
-        - mappings
-        - query_cache
-        - segments
-        - shards
-        - store
+      required: []
     CharFilterTypes:
       type: object
       properties:
@@ -271,18 +259,7 @@ components:
           type: array
           items:
             $ref: '_common.yaml#/components/schemas/VersionString'
-      required:
-        - count
-        - discovery_types
-        - fs
-        - ingest
-        - jvm
-        - network_types
-        - os
-        - packaging_types
-        - plugins
-        - process
-        - versions
+      required: []
     ClusterNodeCount:
       type: object
       properties:
@@ -689,3 +666,30 @@ components:
         - avg
         - max
         - min
+    Metric:
+      type: string
+      enum:
+        - _all
+        - discovery_type
+        - fs
+        - indices
+        - ingest
+        - jvm
+        - network_types
+        - os
+        - packaging_types
+        - plugins
+        - process
+    IndexMetric:
+      type: string
+      enum:
+        - _all
+        - analysis
+        - completion
+        - docs
+        - fielddata
+        - mappings
+        - query_cache
+        - segments
+        - shards
+        - store

tests/default/cluster/stats/index_metric.yaml

@@ -0,0 +1,18 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test cluster manager stats.
+# TODO: Re-enable in 3.0, see https://github.com/opensearch-project/opensearch-api-specification/pull/613
+version: '>= 2.18 < 3'
+chapters:
+  - synopsis: Get mapping and analysis indices stats.
+    path: /_cluster/stats/{metric}/{index_metric}/nodes/{node_id}
+    method: GET
+    parameters:
+      node_id: _all
+      metric:
+        - indices
+      index_metric:
+        - analysis
+        - mappings
+    response:
+      status: 200

tests/default/cluster/stats/metric.yaml

@@ -0,0 +1,16 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test cluster manager stats.
+# TODO: Re-enable in 3.0, see https://github.com/opensearch-project/opensearch-api-specification/pull/613
+version: '>= 2.18 < 3'
+chapters:
+  - synopsis: Get nodes fs and jvm stats.
+    path: /_cluster/stats/{metric}/nodes/{node_id}
+    method: GET
+    parameters:
+      node_id: _all
+      metric:
+        - fs
+        - jvm
+    response:
+      status: 200