"Unused request header descriptions" yielded if not directly referenced

[nickvergessen]

In Talk we have a middleware which e.g. takes care of federated authentication. We should therefore document the x-nextcloud-federation header on all controller methods that support federation.
There is 1 inconvenience with this and 1 error:

1. It's duplicating the existing #[FederationSupported] attribute we have and if that one extends RequestHeader it is not reflected in the docs.
2. When adding it manually the openapi-extractor is complaining, even though the header is read in the depth of the middleware:

Error: Avatar#getAvatar: Unused request header descriptions: x-nextcloud-federation
Error: Avatar#getAvatarDark: Unused request header descriptions: x-nextcloud-federation
Error: Avatar#getUserProxyAvatarWithoutRoom: Unused request header descriptions: x-nextcloud-federation
Error: Avatar#getUserProxyAvatarDarkWithoutRoom: Unused request header descriptions: x-nextcloud-federation
Error: Avatar#getUserProxyAvatar: Unused request header descriptions: x-nextcloud-federation
Error: Avatar#getUserProxyAvatarDark: Unused request header descriptions: x-nextcloud-federation

[provokateurin]

The reason why this error is shown is that it is supposed to prevent headers being documented that are never/no longer used. The middleware use-case makes a lot of sense though.
Do you think a third optional parameter to RequesterHeader would be useful to indicate that the header is not used directly in the controller method, but still used? Then hopefully only people who know what they are doing will use the parameter and get told when the header is no longer used in the code.
I don't see another way, unless we also support the attribute on the controller and assume that the middleware will do its thing for all controller methods.

[nickvergessen]

Do you think a third optional parameter to RequesterHeader would be useful to indicate that the header is not used directly in the controller method, but still used? Then hopefully only people who know what they are doing will use the parameter and get told when the header is no longer used in the code.

I'd say this is a good option yeah

[provokateurin]

Added the parameter: nextcloud/server#53283