Removed one of the duplicate '/_nodes/{metric}' and '/_nodes/{node_id}' paths.

[dblock]

Description

Was trying to load the spec with the Ruby openapi3_parser and it failed with this error.

/Users/dblock/.rvm/gems/ruby-3.1.2/gems/openapi3_parser-0.9.2/lib/openapi3_parser/node_factory/map.rb:206:in `validate': Invalid data for #/paths: There are paths that conflict: '/_nodes/{metric}', '/_nodes/{node_id}' (Openapi3Parser::Error::InvalidData)

Now properly detecting dups.

Issues Resolved

List any issues this PR will resolve, e.g. Closes [...].

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

Changes Analysis

Commit SHA: de7fd22
Comparing To SHA: 3441e2b

API Changes

Summary

├─┬Paths
│ ├──[➖] path (2932:3)❌ 
│ ├──[➖] path (2912:3)❌ 
│ └──[➕] path (2912:3)
└─┬Components
  └──[➕] parameters (18927:7)

Document Element	Total Changes	Breaking Changes
paths	3	2
components	1	0

• ❌ BREAKING Changes: 2 out of 4
• Removals: 2
• Additions: 2
• Breaking Removals: 2

Report

The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/9947904959/artifacts/1704051538

API Coverage

	Before	After	Δ
Covered (%)	483 (47.31 %)	483 (47.31 %)	0 (0 %)
Uncovered (%)	538 (52.69 %)	538 (52.69 %)	0 (0 %)
Unknown	24	24	0

[nhtruong]

This will cause a breaking change in the clients. The clients accepts both metric and node_id as params for client.nodes.info() function (js, ruby) and uses the following logic to determine which path to use:

• both metric and node_id are provided: /nodes/{node_id}/{metric}
• only node_id is provided: /nodes/{node_id}
• only metric is provided: /nodes/{metric}
• neither is provided: /nodes

This is another quirk of OpenSearch API.
The server treats/nodes/{node_id} and /nodes/{metric} as an identical endpoint. So this endpoint is actually /nodes/{node_id_or_metric}. But this will cause the generated clients to read node_id_or_metric as the 3rd path param. We can collapse those 2 endpoints into /nodes/{node_id_or_metric} but we will have to add a new x- extension to tell the generator how to handle this edge case.

I'm thinking x-union-param: ['node_id', 'metric'] for the node_id_or_metric path param

[dblock]

I'm thinking x-union-param: ['node_id', 'metric'] for the node_id_or_metric path param

I made the change by introducing /_nodes/{node_id_or_metric}.

I am not sure we're doing the right thing by introducing parameter hints where we try to express that this parameter is actually 2 different possible types. As written in this PR the parameter is node_id_or_metric, and it can now be an array of either a node_id or a metric via schema (anyOf). Perhaps, the right way is for clients to patch this behavior to be backwards compatible instead of the spec requiring a hint, or even examine the type and notice that it can be 1 of 2 things?

[nhtruong]

We should update https://github.com/opensearch-project/opensearch-api-specification/blob/main/CLIENT_GENERATOR_GUIDE.md to alert devs about this edge case as well.

[dblock]

We should update https://github.com/opensearch-project/opensearch-api-specification/blob/main/CLIENT_GENERATOR_GUIDE.md to alert devs about this edge case as well.

Done, d4f3a55.