OpenAPI v3.1: Support for $ref siblings

[lcawl]

🚀 Feature Proposal

As a motivation for upgrading our OpenAPI generator from OAS 3.0 to OAS 3.1 (or later), it includes support for $ref siblings, per OAI/OpenAPI-Specification#2744

The generator would need to shift to outputting OAS 3.1 files and it would need to start including these sibling descriptions and summaries.

Motivation

We have some schema objects that are used in a lot of places (e.g. QueryContainer in https://github.com/elastic/elasticsearch-specification/blob/main/specification/_types/query_dsl/abstractions.ts). The specifications that use that object have additional descriptions (e.g. the DatafeedConfig query has a unique description of its default behaviour). However, that information is currently missing from the OpenAPI 3.0 document since there's no way to override the shared QueryContainer object's description.

Example

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"
          },