[Feedback]: Repetitive header parameters

[lcawl]

Was the documentation helpful?

Yes

What documentation page is affected

The generated content in the Kibana APIs, for example the operations under https://www.elastic.co/docs/api/doc/kibana/group/endpoint-roles

Description

Per feedback from @sophiec20 can avoid repeating common parameters (e.g. the elastic-api-version)?

This will require investigation of whether OpenAPI supports defining parameters at a document level rather than at an operation level. If it's supported, it will be a matter of confirming that we can create those via the OpenAPI generator and that they display as expected when published.

ES_FEEDBACK_ID: lVtk2pIBWCMSeP1od2Y_

[lcawl]

Per https://swagger.io/docs/specification/v3_0/describing-parameters/#common-parameters you can have:

• Common parameters for all methods of a path: "Parameters shared by all operations of a path can be defined on the path level instead of the operation level. Path-level parameters are inherited by all operations of that path", and
• Common parameters for various paths: "Note that the parameters defined in components are not parameters applied to all operations — they are simply global definitions that can be easily re-used"

I tested that in both cases the "common parameters" are displayed for each affected operation in Bump.sh. IMO this is appropriate behaviour, since otherwise you're assuming users know to scroll up to find the full set of parameters defined somewhere else on the site. If it is the desired behaviour to have a set of parameters (e.g. elastic-api-version) that is applicable across all operations but not listed under each operation, I think the only way to accomplish this would be to remove it from the automated API document and describe it in an introductory topic instead (like we've done for the space ID in https://www.elastic.co/docs/api/doc/kibana/topic/topic-kibana-spaces). IMO this would only be acceptable if the parameter has the same supported values for all operations.