[DOCS] Settings API improvements

[lcawl]

🚀 Feature Proposal

There are outstanding issues with the way setting APIs are represented in the Elasticsearch specification (per @elastic/devtools-team investigation and issues like #2274).

IMO we should:

1. Augment the documentation with details from the @elastic/devtools-team about all the valid ways to update settings
2. Fix or remove the way that the recursive setting definitions appear in the OpenAPI documents, since IMO they're currently inaccurate. For example, this might mean we just refer to the settings reference pages for the definitive list of valid settings, rather than repeating them in the API reference. Maybe this could be accomplished by using x-model same as we do for Query DSL references (e.g. in

   elasticsearch-specification/docs/overlays/elasticsearch-shared-overlays.yaml

   Line 228 in d0fded3

   # Add x-model and/or abbreviate schemas that should point to other references

   or longer-term in the spec per Generate x-model in OpenAPI output #3034)

Motivation

Improve the accuracy of the index, cluster settings guidance.
Have a single source of truth for the full list of Elasticsearch settings that can be updated via APIs.

Example

@pquentin shared some details that AFAIK are not represented in our current docs (e.g. https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings, https://www.elastic.co/docs/deploy-manage/stack-settings, https://www.elastic.co/docs/reference/elasticsearch/index-settings/, etc). For example:

...Historically, settings were a flat list of properties with dotted names to describe a hierarchy of related settings (e.g. indices.recovery.max_bytes_per_sec). Later, the ability to represent them as a hierarchy of nested JSON objects was added. These two representations coexist in ES, meaning that the request below is correct. The last value encountered in JSON parsing order (i.e. text order) takes precedence.

PUT /_cluster/settings
{
  "transient" : {
     "indices": {
        "recovery": {
            "max_bytes_per_sec": "20mb"
          }
      },
      "indices.recovery.max_bytes_per_sec" : "20mb"
  }
}

In the specific case of cluster settings, wildcards can be used to reset a set of values at once. We illustrate below both hierarchical and flat representations:

PUT /_cluster/settings
{
  "transient" : {
    "indices": {
      "*": null
    },
    "indices.*" : null
  }
}

... Because of... semantic redundancy, APIs accepting index settings allow, as a convenience, these settings to be represented with and without the “index” prefix. This is implemented by updating the map representing settings so that all keys have the same prefix. This method is used only with index settings in the entire ES code base, with one exception. The 3 requests below are therefore equivalent:

PUT /test2/_settings
{
  "number_of_replicas": 1
}

PUT /test2/_settings
{
  "index": {
    "number_of_replicas": 1 
  }
}

PUT /test2/_settings
{
  "index.number_of_replicas": 1
}

And we can mix all variants in a single request. The request below is valid and will set the number of replicas to 1:

PUT /test2/_settings
{
  "number_of_replicas": 3,
  "index.number_of_replicas": 2,
  "index": {
    "number_of_replicas": 1
  }
}

[shainaraskas]

Split out conceptual/instructional content into elastic/docs-content#1579. Some of it still might need to be included in the spec