Correct specification mismatches (#244)

* `node.stats::query.groups` should be `string[]` not `boolean` Signed-off-by: Thomas Farr <tsfarr@amazon.com> * Re-add `/_nodes/{metric}` nodes.info path Signed-off-by: Thomas Farr <tsfarr@amazon.com> * Correct cat.nodes record shape Signed-off-by: Thomas Farr <tsfarr@amazon.com> * Change references on `local` param to "cluster-manager" node to match others. Signed-off-by: Thomas Farr <tsfarr@amazon.com> * cluster.health::query.level also accepts `awareness_attributes` Signed-off-by: Thomas Farr <tsfarr@amazon.com> * Bytes also accepts the non `b` suffixed variants Signed-off-by: Thomas Farr <tsfarr@amazon.com> * Define metric enums Signed-off-by: Thomas Farr <tsfarr@amazon.com> * /_component_template APIs don't actually accept comma-separated lists Signed-off-by: Thomas Farr <tsfarr@amazon.com> * /_index_template APIs don't actually accept comma-separated lists Signed-off-by: Thomas Farr <tsfarr@amazon.com> * Fix lint Signed-off-by: Thomas Farr <tsfarr@amazon.com> * indices.add_block::path.index accepts a list of indices Signed-off-by: Thomas Farr <tsfarr@amazon.com> --------- Signed-off-by: Thomas Farr <tsfarr@amazon.com>
opensearch-project · Apr 16, 2024 · 7a59510 · 7a59510
1 parent 4299a19
commit 7a59510
Show file tree

Hide file tree

Showing 13 changed files with 159 additions and 23 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,6 @@ node_modules
 
 # Jekyll Website
 _site/
+
+# build output
+build/
diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml
@@ -773,10 +773,12 @@ components:
     cluster.delete_component_template::path.name:
       in: path
       name: name
-      description: Comma-separated list or wildcard expression of component template names used to limit the request.
+      description: |-
+        Name of the component template to delete.
+        Wildcard (*) expressions are supported.
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Names'
+        $ref: '../schemas/_common.yaml#/components/schemas/Name'
       style: simple
     cluster.delete_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
@@ -823,11 +825,11 @@ components:
       in: path
       name: name
       description: |-
-        Comma-separated list of component template names used to limit the request.
+        Name of the component template to check existence of.
         Wildcard (*) expressions are supported.
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Names'
+        $ref: '../schemas/_common.yaml#/components/schemas/Name'
       style: simple
     cluster.exists_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
@@ -862,7 +864,7 @@ components:
       in: path
       name: name
       description: |-
-        Comma-separated list of component template names used to limit the request.
+        Name of the component template to retrieve.
         Wildcard (`*`) expressions are supported.
       required: true
       schema:
@@ -990,7 +992,7 @@ components:
       name: level
       description: Can be one of cluster, indices or shards. Controls the details level of the health information returned.
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Level'
+        $ref: '../schemas/cluster.health.yaml#/components/schemas/Level'
       style: form
     cluster.health::query.local:
       in: query
@@ -1286,7 +1288,9 @@ components:
       description: Limit the information returned to the specified metrics
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Metrics'
+        type: array
+        items:
+          $ref: '../schemas/cluster.state.yaml#/components/schemas/Metric'
       style: simple
     cluster.state::query.allow_no_indices:
       in: query
@@ -1326,7 +1330,7 @@ components:
     cluster.state::query.local:
       in: query
       name: local
-      description: 'Return local information, do not retrieve the state from master node (default: false)'
+      description: 'Return local information, do not retrieve the state from cluster-manager node (default: false)'
       schema:
         type: boolean
       style: form

diff --git a/spec/namespaces/indices.yaml b/spec/namespaces/indices.yaml
@@ -2638,7 +2638,7 @@ components:
       description: A comma separated list of indices to add a block to
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/IndexName'
+        $ref: '../schemas/_common.yaml#/components/schemas/Indices'
       style: simple
     indices.add_block::query.allow_no_indices:
       in: query
@@ -3117,10 +3117,10 @@ components:
     indices.delete_index_template::path.name:
       in: path
       name: name
-      description: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.
+      description: Name of the index template to delete. Wildcard (*) expressions are supported.
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Names'
+        $ref: '../schemas/_common.yaml#/components/schemas/Name'
       style: simple
     indices.delete_index_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
@@ -3295,7 +3295,7 @@ components:
     indices.exists_index_template::path.name:
       in: path
       name: name
-      description: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.
+      description: Name of the index template to check existence of. Wildcard (*) expressions are supported.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Name'
@@ -3358,7 +3358,7 @@ components:
     indices.exists_template::query.local:
       in: query
       name: local
-      description: 'Return local information, do not retrieve the state from master node (default: false)'
+      description: 'Return local information, do not retrieve the state from cluster-manager node (default: false)'
       schema:
         type: boolean
       style: form
@@ -3695,7 +3695,7 @@ components:
     indices.get_index_template::path.name:
       in: path
       name: name
-      description: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.
+      description: Name of the index template to retrieve. Wildcard (*) expressions are supported.
       required: true
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Name'

diff --git a/spec/namespaces/nodes.yaml b/spec/namespaces/nodes.yaml
@@ -253,12 +253,27 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/nodes.usage@200'
-  /_nodes/{node_id}:
+  /_nodes/{metric}:
     get:
       operationId: nodes.info.1
       x-operation-group: nodes.info
       x-version-added: '1.0'
       description: Returns information about nodes in the cluster.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/nodes-apis/nodes-info/
+      parameters:
+        - $ref: '#/components/parameters/nodes.info::path.metric'
+        - $ref: '#/components/parameters/nodes.info::query.flat_settings'
+        - $ref: '#/components/parameters/nodes.info::query.timeout'
+      responses:
+        '200':
+          $ref: '#/components/responses/nodes.info@200'
+  /_nodes/{node_id}:
+    get:
+      operationId: nodes.info.2
+      x-operation-group: nodes.info
+      x-version-added: '1.0'
+      description: Returns information about nodes in the cluster.
       externalDocs:
         url: https://opensearch.org/docs/latest/api-reference/nodes-apis/nodes-info/
       parameters:
@@ -423,7 +438,7 @@ paths:
           $ref: '#/components/responses/nodes.usage@200'
   /_nodes/{node_id}/{metric}:
     get:
-      operationId: nodes.info.2
+      operationId: nodes.info.3
       x-operation-group: nodes.info
       x-version-added: '1.0'
       description: Returns information about nodes in the cluster.
@@ -536,7 +551,9 @@ components:
       description: Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest.
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Metrics'
+        type: array
+        items:
+          $ref: '../schemas/nodes.info.yaml#/components/schemas/Metric'
       style: simple
     nodes.info::path.node_id:
       in: path
@@ -583,15 +600,19 @@ components:
       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:
-        $ref: '../schemas/_common.yaml#/components/schemas/Metrics'
+        type: array
+        items:
+          $ref: '../schemas/nodes.stats.yaml#/components/schemas/IndexMetric'
       style: simple
     nodes.stats::path.metric:
       in: path
       name: metric
       description: Limit the information returned to the specified metrics
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Metrics'
+        type: array
+        items:
+          $ref: '../schemas/nodes.stats.yaml#/components/schemas/Metric'
       style: simple
     nodes.stats::path.node_id:
       in: path
@@ -627,7 +648,9 @@ components:
       name: groups
       description: Comma-separated list of search groups to include in the search statistics.
       schema:
-        type: boolean
+        type: array
+        items:
+          type: string
       style: form
     nodes.stats::query.include_segment_file_sizes:
       in: query
@@ -667,7 +690,9 @@ components:
         A comma-separated list of the following options: `_all`, `rest_actions`.
       required: true
       schema:
-        $ref: '../schemas/_common.yaml#/components/schemas/Metrics'
+        type: array
+        items:
+          $ref: '../schemas/nodes.usage.yaml#/components/schemas/Metric'
       style: simple
     nodes.usage::path.node_id:
       in: path

diff --git a/spec/namespaces/snapshot.yaml b/spec/namespaces/snapshot.yaml
@@ -763,7 +763,7 @@ components:
     snapshot.get_repository::query.local:
       in: query
       name: local
-      description: 'Return local information, do not retrieve the state from master node (default: false)'
+      description: 'Return local information, do not retrieve the state from cluster-manager node (default: false)'
       schema:
         type: boolean
       style: form

diff --git a/spec/opensearch-openapi.yaml b/spec/opensearch-openapi.yaml
@@ -358,6 +358,8 @@ paths:
     $ref: 'namespaces/nodes.yaml#/paths/~1_nodes~1usage'
   /_nodes/usage/{metric}:
     $ref: 'namespaces/nodes.yaml#/paths/~1_nodes~1usage~1{metric}'
+  /_nodes/{metric}:
+    $ref: 'namespaces/nodes.yaml#/paths/~1_nodes~1{metric}'
   /_nodes/{node_id}:
     $ref: 'namespaces/nodes.yaml#/paths/~1_nodes~1{node_id}'
   /_nodes/{node_id}/hot_threads:

diff --git a/spec/schemas/_common.yaml b/spec/schemas/_common.yaml
@@ -695,10 +695,15 @@ components:
       type: string
       enum:
         - b
+        - k
         - kb
+        - m
         - mb
+        - g
         - gb
+        - t
         - tb
+        - p
         - pb
     ByteSize:
       oneOf:

diff --git a/spec/schemas/cat.nodes.yaml b/spec/schemas/cat.nodes.yaml
@@ -87,13 +87,25 @@ components:
         node.role:
           description: |-
             The roles of the node.
-            Returned values include `c`(cold node), `d`(data node), `f`(frozen node), `h`(hot node), `i`(ingest node), `l`(machine learning node), `m` (master eligible node), `r`(remote cluster client node), `s`(content node), `t`(transform node), `v`(voting-only node), `w`(warm node),and `-`(coordinating node only).
+            Returned values include `c`(cold node), `d`(data node), `f`(frozen node), `h`(hot node), `i`(ingest node), `l`(machine learning node), `m` (cluster-manager eligible node), `r`(remote cluster client node), `s`(content node), `t`(transform node), `v`(voting-only node), `w`(warm node),and `-`(coordinating node only).
+          type: string
+        node.roles:
+          description: |-
+            A comma-separated list of the roles of the node.
+            Returned values may include but are not limited to: `data`, `ingest`, `master`, `cluster_manager`, `remote_cluster_client`, `search`, and `-`(coordinating node only).
+          type: string
+        cluster_manager:
+          description: |-
+            Indicates whether the node is the elected cluster-manager node.
+            Returned values include `*`(elected cluster-manager) and `-`(not elected cluster-manager).
           type: string
         master:
           description: |-
             Indicates whether the node is the elected master node.
             Returned values include `*`(elected master) and `-`(not elected master).
           type: string
+          x-version-deprecated: 2.0.0
+          x-deprecation-message: To promote inclusive language, use 'cluster_manager' instead.
         name:
           $ref: '_common.yaml#/components/schemas/Name'
         completion.size:

diff --git a/spec/schemas/cluster.health.yaml b/spec/schemas/cluster.health.yaml
@@ -104,6 +104,13 @@ components:
         - relocating_shards
         - status
         - unassigned_shards
+    Level:
+      type: string
+      enum:
+        - cluster
+        - indices
+        - shards
+        - awareness_attributes
     ShardHealthStats:
       type: object
       properties:

diff --git a/spec/schemas/cluster.state.yaml b/spec/schemas/cluster.state.yaml
@@ -0,0 +1,20 @@
+openapi: 3.1.0
+info:
+  title: Schemas of cluster.state category
+  description: Schemas of cluster.state category
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    Metric:
+      type: string
+      enum:
+        - blocks
+        - metadata
+        - nodes
+        - routing_table
+        - routing_nodes
+        - master_node
+        - cluster_manager_node
+        - version
+        - _all
diff --git a/spec/schemas/nodes.info.yaml b/spec/schemas/nodes.info.yaml
@@ -6,6 +6,22 @@ info:
 paths: {}
 components:
   schemas:
+    Metric:
+      type: string
+      enum:
+        - settings
+        - os
+        - process
+        - jvm
+        - thread_pool
+        - transport
+        - http
+        - plugins
+        - ingest
+        - aggregations
+        - indices
+        - search_pipelines
+        - _all
     ResponseBase:
       allOf:
         - $ref: 'nodes._common.yaml#/components/schemas/NodesResponseBase'

diff --git a/spec/schemas/nodes.stats.yaml b/spec/schemas/nodes.stats.yaml
@@ -6,6 +6,43 @@ info:
 paths: {}
 components:
   schemas:
+    Metric:
+      type: string
+      enum:
+        - breaker
+        - fs
+        - http
+        - indices
+        - jvm
+        - os
+        - process
+        - thread_pool
+        - transport
+        - discovery
+        - indexing_pressure
+        - search_pipeline
+        - _all
+    IndexMetric:
+      type: string
+      enum:
+        - store
+        - indexing
+        - get
+        - search
+        - merge
+        - flush
+        - refresh
+        - query_cache
+        - fielddata
+        - docs
+        - warmer
+        - completion
+        - segments
+        - translog
+        - suggest
+        - request_cache
+        - recovery
+        - _all
     ResponseBase:
       allOf:
         - $ref: 'nodes._common.yaml#/components/schemas/NodesResponseBase'

diff --git a/spec/schemas/nodes.usage.yaml b/spec/schemas/nodes.usage.yaml
@@ -6,6 +6,11 @@ info:
 paths: {}
 components:
   schemas:
+    Metric:
+      type: string
+      enum:
+        - rest_actions
+        - _all
     ResponseBase:
       allOf:
         - $ref: 'nodes._common.yaml#/components/schemas/NodesResponseBase'
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,3 +12,6 @@ node_modules @@
     # Jekyll Website
     _site/
+    # build output
+    build/