Support for $ref siblings or improve nested descriptions

[lcawl]

🚀 Feature Proposal

AFAIK OpenAPI 3.1 (or later), supports $ref siblings (per OAI/OpenAPI-Specification#2744), but OpenAPI 3.0 and earlier does not.

This means that in the current implementation if we use a shared object, we can't also override or append to its description.
If we're not moving to OpenAPI 3.1 or later any time soon, it would be nice if our OpenAPI generator could ensure the descriptions were carried over (especially if the inherited object doesn't contain a description). Relates to #4473?

Motivation

We have some schema objects that are used in a lot of places. The specifications that use that object can have additional descriptions. However, that information is currently missing from the OpenAPI 3.0 document since there's no way to override or augment the shared object's description.

Example 1

The rate_limit object in https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put-googlevertexai is missing a description.

This is because in https://github.com/elastic/elasticsearch-specification/blob/main/specification/inference/put_googlevertexai/PutGoogleVertexAiRequest.ts the body contains

    /**
     * Settings used to install the inference model. These settings are specific to the `googlevertexai` service.
     */
    service_settings: GoogleVertexAIServiceSettings

...which is defined in https://github.com/elastic/elasticsearch-specification/blob/main/specification/inference/_types/CommonTypes.ts as follows:

  /**
   * This setting helps to minimize the number of rate limit errors returned from Google Vertex AI.
   * By default, the `googlevertexai` service sets the number of requests allowed per minute to 30.000.
   */
  rate_limit?: RateLimitSetting

But RateLimitSetting is defined in https://github.com/elastic/elasticsearch-specification/blob/main/specification/inference/_types/Services.ts as follows:

export class RateLimitSetting {
  /**
   * The number of requests allowed per minute.
   */
  requests_per_minute?: integer
}

The descriptions are carried over into the schema.json file, but the This setting helps to minimize the number of rate limit... description is missing from the OpenAPI output:

...
      "inference._types.GoogleVertexAIServiceSettings": {
        "type": "object",
        "properties": {
          "rate_limit": {
            "$ref": "#/components/schemas/inference._types.RateLimitSetting"
...
      "inference._types.RateLimitSetting": {
        "type": "object",
        "properties": {
          "requests_per_minute": {
            "description": "The number of requests allowed per minute.",
            "type": "number"
          }
        }
      },

Example 2

Here's an example of what is currently output for the datafeed_config in an OpenAPI v3.0 document (it looks the same for all the ~90 places that QueryContainer is referenced):

...
     "ml._types:DatafeedConfig": {
        "type": "object",
        "properties": {
          ...
          "query": {
            "$ref": "#/components/schemas/_types.query_dsl:QueryContainer"
          },

This is what I think we could accomplish instead in an OpenAPI 3.1 document:

     "ml._types:DatafeedConfig": {
        "type": "object",
        "properties": {
          ...
          "query": {
            "description": "...By default, this property has the following value: `{"match_all": {"boost": 1}}`.",
            "$ref": "#/components/schemas/_types.query_dsl:QueryContainer"
          },

I don't think this specific case is reasonable to try to solve in OpenAPI 3.0, since it seems to me you'd need to basically create another copy of the "_types.query_dsl:QueryContainer" (e.g. "_types.query_dsl:QueryContainerForDatafeedConfig") and replace or append to the inherited description)).