From 85a153427020508f7266cff29eb033273c402f31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Fri, 20 Sep 2024 09:20:25 +0200 Subject: [PATCH] Adds cluster API example requests and responses (#2870) Co-authored-by: lcawl --- .../elasticsearch-openapi-overlays.yaml | 69 ++++++++++++++++++- ...usterAllocationExplainRequestExample1.json | 7 ++ .../health/clusterHealthResponseExample1.json | 7 ++ .../clusterPutSettingsRequestExample1.json | 7 ++ .../clusterRerouteRequestExample1.json | 7 ++ .../nodes/info/nodesInfoResponseExample1.json | 7 ++ .../nodes/info/nodesInfoResponseExample1.yaml | 5 ++ ...esReloadSecureSettingsRequestExample1.json | 7 ++ ...sReloadSecureSettingsResponseExample1.json | 7 ++ .../tasks/get/getTasksResponseExample1.json | 7 ++ 10 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 specification/cluster/allocation_explain/clusterAllocationExplainRequestExample1.json create mode 100644 specification/cluster/health/clusterHealthResponseExample1.json create mode 100644 specification/cluster/put_settings/clusterPutSettingsRequestExample1.json create mode 100644 specification/cluster/reroute/clusterRerouteRequestExample1.json create mode 100644 specification/nodes/info/nodesInfoResponseExample1.json create mode 100644 specification/nodes/info/nodesInfoResponseExample1.yaml create mode 100644 specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsRequestExample1.json create mode 100644 specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsResponseExample1.json create mode 100644 specification/tasks/get/getTasksResponseExample1.json diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml index f05eef369e..64b359732a 100644 --- a/docs/overlays/elasticsearch-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-openapi-overlays.yaml @@ -40,4 +40,71 @@ actions: examples: resetFeaturesResponseExample1: $ref: "../../specification/features/reset_features/ResetFeaturesResponseExample1.json" - \ No newline at end of file + - target: "$.components['requestBodies']['cluster.allocation_explain']" + description: "Add examples for cluster allocation explain operation" + update: + content: + application/json: + examples: + clusterAllocationExplainRequestExample1: + $ref: "../../specification/cluster/allocation_explain/clusterAllocationExplainRequestExample1.json" + - target: "$.components['responses']['cluster.health#200']" + description: "Add examples for cluster health operation" + update: + content: + application/json: + examples: + clusterHealthResponseExample1: + $ref: "../../specification/cluster/health/clusterHealthResponseExample1.json" + - target: "$.paths['/_cluster/settings']['put']" + description: "Add examples for cluster update settings operation" + update: + requestBody: + content: + application/json: + examples: + clusterPutSettingsRequestExample1: + $ref: "../../specification/cluster/put_settings/clusterPutSettingsRequestExample1.json" + - target: "$.paths['/_cluster/reroute']['post']" + description: "Add examples for cluster reroute operation" + update: + requestBody: + content: + application/json: + examples: + clusterRerouteRequestExample1: + $ref: "../../specification/cluster/reroute/clusterRerouteRequestExample1.json" + - target: "$.components['requestBodies']['nodes.reload_secure_settings']" + description: "Add examples for nodes reload secure settings operation" + update: + content: + application/json: + examples: + clusterNodesReloadSecureSettingsRequestExample1: + $ref: "../../specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsRequestExample1.json" + - target: "$.components['responses']['nodes.reload_secure_settings#200']" + description: "Add response examples for nodes reload secure settings operation" + update: + content: + application/json: + examples: + clusterNodesReloadSecureSettingsResponseExample1: + $ref: "../../specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsResponseExample1.json" + - target: "$.paths['/_tasks']['get']" + description: "Add examples for task management operation" + update: + responses: + 200: + content: + application/json: + examples: + getTasksResponseExample1: + $ref: "../../specification/tasks/get/getTasksResponseExample1.json" + - target: "$.components['responses']['nodes.info#200']" + description: "Add response examples for nodes info" + update: + content: + application/json: + examples: + nodesInfoResponseExample1: + $ref: "../../specification/nodes/info/nodesInfoResponseExample1.yaml" \ No newline at end of file diff --git a/specification/cluster/allocation_explain/clusterAllocationExplainRequestExample1.json b/specification/cluster/allocation_explain/clusterAllocationExplainRequestExample1.json new file mode 100644 index 0000000000..028ed4e818 --- /dev/null +++ b/specification/cluster/allocation_explain/clusterAllocationExplainRequestExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "Provides an explanation for a shard’s current allocation.", + "method_request": "GET _cluster/allocation/explain", + "description": "", + "type": "request", + "value": "{\n \"index\": \"my-index-000001\",\n \"shard\": 0,\n \"primary\": false,\n \"current_node\": \"my-node\"\n}" +} diff --git a/specification/cluster/health/clusterHealthResponseExample1.json b/specification/cluster/health/clusterHealthResponseExample1.json new file mode 100644 index 0000000000..fbf688b042 --- /dev/null +++ b/specification/cluster/health/clusterHealthResponseExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "A successful response when requesting the health status of a cluster.", + "description": "This is the API response in case of a quiet single node cluster with a single index with one shard and one replica.", + "type": "response", + "response_code": 200, + "value": "{\n \"cluster_name\" : \"testcluster\",\n \"status\" : \"yellow\",\n \"timed_out\" : false,\n \"number_of_nodes\" : 1,\n \"number_of_data_nodes\" : 1,\n \"active_primary_shards\" : 1,\n \"active_shards\" : 1,\n \"relocating_shards\" : 0,\n \"initializing_shards\" : 0,\n \"unassigned_shards\" : 1,\n \"delayed_unassigned_shards\": 0,\n \"number_of_pending_tasks\" : 0,\n \"number_of_in_flight_fetch\": 0,\n \"task_max_waiting_in_queue_millis\": 0,\n \"active_shards_percent_as_number\": 50.0\n}" +} diff --git a/specification/cluster/put_settings/clusterPutSettingsRequestExample1.json b/specification/cluster/put_settings/clusterPutSettingsRequestExample1.json new file mode 100644 index 0000000000..45cba7ab50 --- /dev/null +++ b/specification/cluster/put_settings/clusterPutSettingsRequestExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "Configures dynamic cluster settings.", + "method_request": "PUT /_cluster/settings", + "description": "An example of a persistent update.", + "type": "request", + "value": "{\n \"persistent\" : {\n \"indices.recovery.max_bytes_per_sec\" : \"50mb\"\n }\n}" +} diff --git a/specification/cluster/reroute/clusterRerouteRequestExample1.json b/specification/cluster/reroute/clusterRerouteRequestExample1.json new file mode 100644 index 0000000000..a5210c6f83 --- /dev/null +++ b/specification/cluster/reroute/clusterRerouteRequestExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "Changes the allocation of shards in a cluster.", + "method_request": "POST /_cluster/reroute?metric=none", + "description": "", + "type": "request", + "value": "{\n \"commands\": [\n {\n \"move\": {\n \"index\": \"test\", \"shard\": 0,\n \"from_node\": \"node1\", \"to_node\": \"node2\"\n }\n },\n {\n \"allocate_replica\": {\n \"index\": \"test\", \"shard\": 1,\n \"node\": \"node3\"\n }\n }\n ]\n}" +} diff --git a/specification/nodes/info/nodesInfoResponseExample1.json b/specification/nodes/info/nodesInfoResponseExample1.json new file mode 100644 index 0000000000..04ace45464 --- /dev/null +++ b/specification/nodes/info/nodesInfoResponseExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "A successful response when requesting cluster nodes information.", + "description": "", + "type": "response", + "response_code": 200, + "value": "{\n \"_nodes\": \"...\",\n \"cluster_name\": \"elasticsearch\",\n \"nodes\": {\n \"USpTGYaBSIKbgSUJR2Z9lg\": {\n \"name\": \"node-0\",\n \"transport_address\": \"192.168.17:9300\",\n \"host\": \"node-0.elastic.co\",\n \"ip\": \"192.168.17\",\n \"version\": \"{version}\",\n \"transport_version\": 100000298,\n \"index_version\": 100000074,\n \"component_versions\": {\n \"ml_config_version\": 100000162,\n \"transform_config_version\": 100000096\n },\n \"build_flavor\": \"default\",\n \"build_type\": \"{build_type}\",\n \"build_hash\": \"587409e\",\n \"roles\": [\n \"master\",\n \"data\",\n \"ingest\"\n ],\n \"attributes\": {},\n \"plugins\": [\n {\n \"name\": \"analysis-icu\",\n \"version\": \"{version}\",\n \"description\": \"The ICU Analysis plugin integrates Lucene ICU module into elasticsearch, adding ICU relates analysis components.\",\n \"classname\": \"org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin\",\n \"has_native_controller\": false\n }\n ],\n \"modules\": [\n {\n \"name\": \"lang-painless\",\n \"version\": \"{version}\",\n \"description\": \"An easy, safe and fast scripting language for Elasticsearch\",\n \"classname\": \"org.elasticsearch.painless.PainlessPlugin\",\n \"has_native_controller\": false\n }\n ]\n }\n }\n}" +} diff --git a/specification/nodes/info/nodesInfoResponseExample1.yaml b/specification/nodes/info/nodesInfoResponseExample1.yaml new file mode 100644 index 0000000000..408f338c02 --- /dev/null +++ b/specification/nodes/info/nodesInfoResponseExample1.yaml @@ -0,0 +1,5 @@ +summary: 200 Successful response +description: A successful response when requesting cluster nodes information. +# type: response +# response_code: 200 +value: "{\n \"_nodes\": \"...\",\n \"cluster_name\": \"elasticsearch\",\n \"nodes\": {\n \"USpTGYaBSIKbgSUJR2Z9lg\": {\n \"name\": \"node-0\",\n \"transport_address\": \"192.168.17:9300\",\n \"host\": \"node-0.elastic.co\",\n \"ip\": \"192.168.17\",\n \"version\": \"{version}\",\n \"transport_version\": 100000298,\n \"index_version\": 100000074,\n \"component_versions\": {\n \"ml_config_version\": 100000162,\n \"transform_config_version\": 100000096\n },\n \"build_flavor\": \"default\",\n \"build_type\": \"{build_type}\",\n \"build_hash\": \"587409e\",\n \"roles\": [\n \"master\",\n \"data\",\n \"ingest\"\n ],\n \"attributes\": {},\n \"plugins\": [\n {\n \"name\": \"analysis-icu\",\n \"version\": \"{version}\",\n \"description\": \"The ICU Analysis plugin integrates Lucene ICU module into elasticsearch, adding ICU relates analysis components.\",\n \"classname\": \"org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin\",\n \"has_native_controller\": false\n }\n ],\n \"modules\": [\n {\n \"name\": \"lang-painless\",\n \"version\": \"{version}\",\n \"description\": \"An easy, safe and fast scripting language for Elasticsearch\",\n \"classname\": \"org.elasticsearch.painless.PainlessPlugin\",\n \"has_native_controller\": false\n }\n ]\n }\n }\n}" diff --git a/specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsRequestExample1.json b/specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsRequestExample1.json new file mode 100644 index 0000000000..07744936fa --- /dev/null +++ b/specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsRequestExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "Reloads the keystore on nodes in the cluster.", + "method_request": "POST _nodes/reload_secure_settings", + "description": "", + "type": "request", + "value": "{\n \"secure_settings_password\":\"keystore-password\"\n}" +} diff --git a/specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsResponseExample1.json b/specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsResponseExample1.json new file mode 100644 index 0000000000..935831d6ac --- /dev/null +++ b/specification/nodes/reload_secure_settings/clusterNodesReloadSecureSettingsResponseExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "A successful response when reloading keystore on nodes in your cluster.", + "description": "", + "type": "response", + "response_code": 200, + "value": "{\n \"_nodes\": {\n \"total\": 1,\n \"successful\": 1,\n \"failed\": 0\n },\n \"cluster_name\": \"my_cluster\",\n \"nodes\": {\n \"pQHNt5rXTTWNvUgOrdynKg\": {\n \"name\": \"node-0\"\n }\n }\n}" +} diff --git a/specification/tasks/get/getTasksResponseExample1.json b/specification/tasks/get/getTasksResponseExample1.json new file mode 100644 index 0000000000..437bf2ab50 --- /dev/null +++ b/specification/tasks/get/getTasksResponseExample1.json @@ -0,0 +1,7 @@ +{ + "summary": "A successful response when requesting information about the tasks currently executing in the cluster.", + "description": "", + "type": "response", + "response_code": "", + "value": "{\n \"nodes\" : {\n \"oTUltX4IQMOUUVeiohTt8A\" : {\n \"name\" : \"H5dfFeA\",\n \"transport_address\" : \"127.0.0.1:9300\",\n \"host\" : \"127.0.0.1\",\n \"ip\" : \"127.0.0.1:9300\",\n \"tasks\" : {\n \"oTUltX4IQMOUUVeiohTt8A:124\" : {\n \"node\" : \"oTUltX4IQMOUUVeiohTt8A\",\n \"id\" : 124,\n \"type\" : \"direct\",\n \"action\" : \"cluster:monitor/tasks/lists[n]\",\n \"start_time_in_millis\" : 1458585884904,\n \"running_time_in_nanos\" : 47402,\n \"cancellable\" : false,\n \"parent_task_id\" : \"oTUltX4IQMOUUVeiohTt8A:123\"\n },\n \"oTUltX4IQMOUUVeiohTt8A:123\" : {\n \"node\" : \"oTUltX4IQMOUUVeiohTt8A\",\n \"id\" : 123,\n \"type\" : \"transport\",\n \"action\" : \"cluster:monitor/tasks/lists\",\n \"start_time_in_millis\" : 1458585884904,\n \"running_time_in_nanos\" : 236042,\n \"cancellable\" : false\n }\n }\n }\n }\n}" +}