Add support for Elastic-Api-Version header parameter

[lcawl]

🚀 Feature Proposal

1. Add Elastic-Api-Version header parameter support within the specification.
2. Provide a consistent way to qualify behaviour or request/response bodies that differ depending on the header value.

It seems possible this will be easier to implement in future OpenAPI specification versions (e.g. "Support APIs that have different responses based on query parameters, headers and request bodies" mentioned in https://bump.sh/blog/openapi-v4-moonwalk). There doesn't seem to be an official ETA for that release, however, so we need an interim way to move forward.

Motivation

The openAPI documents generated from the specification are currently missing the Elastic-Api-Version header parameter.

Example

In the generated Kibana openAPI documents, this parameter is output as follows:

...
"parameters": [
          {
            "description": "The version of the API to use",
            "in": "header",
            "name": "elastic-api-version",
            "schema": {
              "default": "2023-10-31",
              "enum": [
                "2023-10-31"
              ],
              "type": "string"
            }
          },

To indicate that a request/response body is associated with a specific version, they're qualifying it like this:

"responses": {
          "200": {
            "content": {
              "application/json; Elastic-Api-Version=2023-10-31": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/core_status_response"
                    },
                   ...

Ideally we would want the openAPI document to contain all of the supported Elastic-Api-Version values for a particular branch (and all of the appropriate request and response body variations that match those versions if they differ).