From 7a59510d30200b22792fb0bd5dd827b620030f89 Mon Sep 17 00:00:00 2001 From: Thomas Farr Date: Tue, 16 Apr 2024 23:28:28 +1200 Subject: [PATCH] Correct specification mismatches (#244) * `node.stats::query.groups` should be `string[]` not `boolean` Signed-off-by: Thomas Farr * Re-add `/_nodes/{metric}` nodes.info path Signed-off-by: Thomas Farr * Correct cat.nodes record shape Signed-off-by: Thomas Farr * Change references on `local` param to "cluster-manager" node to match others. Signed-off-by: Thomas Farr * cluster.health::query.level also accepts `awareness_attributes` Signed-off-by: Thomas Farr * Bytes also accepts the non `b` suffixed variants Signed-off-by: Thomas Farr * Define metric enums Signed-off-by: Thomas Farr * /_component_template APIs don't actually accept comma-separated lists Signed-off-by: Thomas Farr * /_index_template APIs don't actually accept comma-separated lists Signed-off-by: Thomas Farr * Fix lint Signed-off-by: Thomas Farr * indices.add_block::path.index accepts a list of indices Signed-off-by: Thomas Farr --------- Signed-off-by: Thomas Farr --- .gitignore | 3 +++ spec/namespaces/cluster.yaml | 20 +++++++++------- spec/namespaces/indices.yaml | 12 +++++----- spec/namespaces/nodes.yaml | 39 ++++++++++++++++++++++++++------ spec/namespaces/snapshot.yaml | 2 +- spec/opensearch-openapi.yaml | 2 ++ spec/schemas/_common.yaml | 5 ++++ spec/schemas/cat.nodes.yaml | 14 +++++++++++- spec/schemas/cluster.health.yaml | 7 ++++++ spec/schemas/cluster.state.yaml | 20 ++++++++++++++++ spec/schemas/nodes.info.yaml | 16 +++++++++++++ spec/schemas/nodes.stats.yaml | 37 ++++++++++++++++++++++++++++++ spec/schemas/nodes.usage.yaml | 5 ++++ 13 files changed, 159 insertions(+), 23 deletions(-) create mode 100644 spec/schemas/cluster.state.yaml diff --git a/.gitignore b/.gitignore index c13ed1f10..c16dd7893 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,6 @@ node_modules # Jekyll Website _site/ + +# build output +build/ \ No newline at end of file diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml index 3de22a116..b99b49203 100644 --- 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 index 5c4ebdd6c..d5f3824f6 100644 --- 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 index ccffa85de..e0ed1f03e 100644 --- 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,7 +600,9 @@ 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 @@ -591,7 +610,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/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 index 6adb93040..26cfe0796 100644 --- 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 index dffbd314c..23caf7ddd 100644 --- 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 index a9597561f..952b6326f 100644 --- 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 index c02ee4a34..f1d030400 100644 --- 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 index 5a29f9a26..6617140c2 100644 --- 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 new file mode 100644 index 000000000..c8539e69b --- /dev/null +++ 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 \ No newline at end of file diff --git a/spec/schemas/nodes.info.yaml b/spec/schemas/nodes.info.yaml index e6e327003..15b3d9d83 100644 --- 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 index 448daf82e..507b9abd2 100644 --- 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 index eee123550..06a453bbb 100644 --- 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'