Default value missing from OpenAPI output

[lcawl]

There seem to be cases where a default value specified in the typescript file is missing from the OpenAPI output. For example, in https://github.com/elastic/elasticsearch-specification/blob/main/specification/inference/text_embedding/TextEmbeddingRequest.ts

... there is a query parameter with a default value as follows:

  query_parameters: {
    /**
     * Specifies the amount of time to wait for the inference request to complete.
     * @server_default 30s
     */
    timeout?: Duration

However, that default is missing from both the docs-specific and generic output elasticsearch-openapi.json file:

          {
            "in": "query",
            "name": "timeout",
            "description": "Specifies the amount of time to wait for the inference request to complete.",
            "deprecated": false,
            "schema": {
              "$ref": "#/components/schemas/_types.Duration"
            },
            "style": "form"
          }

...
      "_types.Duration": {
        "description": "A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and\n`d` (days). Also accepts \"0\" without a unit and \"-1\" to indicate an unspecified value.",
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "string",
            "enum": [
              "-1"
            ]
          },
          {
            "type": "string",
            "enum": [
              "0"
            ]
          }
        ]
      },

This makes me wonder if the generator ought to consolidate that info rather than using a $ref. Specifically for cases where we're trying to add more info (such as default values) to the re-used type. For example, create this output instead:

  {
            "in": "query",
            "name": "timeout",
            "description": "Specifies the amount of time to wait for the inference request to complete. ",
            "deprecated": false,
            "schema": {
                "default": "30s"
                "oneOf": [
                  {
                    "type": "string"
                  },
                 {
                    "type": "string",
                    "enum": [
                      "-1"
                    ]
                  },
                 {
                    "type": "string",
                    "enum": [
                      "0"
                    ]
                  }
                ]
              },

[Edited Oct 1]
Per #5369 (comment) rather than inlining the full schema, it seems like using an allOf might be another option.

[pquentin]

This makes sense! The schema.json file does include the 30s server default at the query parameter, so that should be possible to fix.

Inlining the full schema sounds harder and would make the OpenAPI files much larger.

[lcawl]

In case this helps devise a possible solution, I tried playing with this in Swagger Editor and it generated the following advice:

"Sibling values alongside $refs are ignored. To add properties to a $ref, wrap the $ref into allOf, or move the extra properties into the referenced definition (if applicable)."

I tried the the allOf workaround as follows in OpenAPI 3.0.1:

         - in: query
          name: timeout
          description: Specifies the amount of time to wait for the inference request to complete.
          deprecated: false
          schema:
            allOf:
             - $ref: '#/components/schemas/_types.Duration'
             - default: 30s
          style: form

... which seemed to work within Swagger Editor, for example:

In OpenAPI 3.1.0 since ref siblings are supported, the following also worked:

          {
            "in": "query",
            "name": "timeout",
            "description": "Specifies the amount of time to wait for the inference request to complete.",
            "deprecated": false,
            "schema": {
              "$ref": "#/components/schemas/_types.Duration",
              "default": "30s"
            },
            "style": "form"
          }

However, neither of these options worked in Bump.sh (i.e. the default value isn't displayed):

Thus if we're going to move forward with either using allOf or upgrading to 3.1.0, lmk and I'll need to follow up on why it doesn't work in Bump.sh

[lcawl]

Feedback so far from Bump.sh is that "Wrapping everything in an allOf indeed seems to be the right way to do it", so I think we ought to integrate this into the generator and then we'll be good to go when this is working on the display side.