Common query parameters omitted from OpenAPI

[lcawl]

priority: med
effort: depends on solution

Problem

There are common query parameters that are applicable to all the CAT APIs, for example the verbose, format, sort, help etc covered in https://www.elastic.co/guide/en/elasticsearch/reference/master/cat.html#common-parameters However they're missing from the OpenAPI documents.

Example

I can see that they're defined in the specification in

elasticsearch-specification/specification/_spec_utils/behaviors.ts

Line 90 in 2397e31

export interface CommonCatQueryParameters {

However, they don't show up in the OpenAPI output.

For example, in https://github.com/elastic/elasticsearch-specification/blob/main/output/openapi/elasticsearch-openapi.json the "cat aliases" operation shows only the parameters that are defined explicitly in https://github.com/elastic/elasticsearch-specification/blob/main/specification/cat/aliases/CatAliasesRequest.ts

 "operationId": "cat-aliases",
        "parameters": [
          {
            "$ref": "#/components/parameters/cat.aliases#expand_wildcards"
          },
          {
            "$ref": "#/components/parameters/cat.aliases#master_timeout"
          }
        ],

Do we need to add them to all the request definitions? Or is there a simple fix to get the CommonCatQueryParameters to resolve?

[lcawl]

Per discussion with @swallez "The common parameters are indeed not present in the OpenAPI output. The idea was to mimic what was in the doc and avoid having them shown for every API endpoint, for readability purposes. Now the bad side effect is that they actually disappear entirely...We can indeed include them in the OpenAPI output but... if they're linked to requests, they will be expanded everywhere. That's a lot of noise, that was rightfully avoided in the old docs"

Some possible solutions are:

• Get the common parameters added to the specification then pursue display improvements such as collapsing parameter lists
• Put the common parameters in the tag description, so they'll appear in the introduction to the "cat" grouping of APIs, similar to how it was handled in the old docs. IMO this is less ideal since it's hiding pertinent details in a description, but it would be feasible if necessary especially if [OpenAPI] Automatically generate the list of tags #2984 is addressed.