Document incoming headers and body

[nickvergessen]

Similarly to https://github.com/nextcloud/spreed/blob/eca3161d246eac7e874a17ee3b747bb0129bee7b/docs/recording.md?plain=1#L120-L125

[provokateurin]

What about adding an attribute for request headers? I don't think we can implement this in some way that is possible to validate by psalm.

As for the request body it's more complicated, as it should be possible to use the doc types to describe it, but that is not possible within an attribute.

[provokateurin]

For the request body I'm not sure what we want. Just an attribute to say that there is a request body with unknown schema (could even be list or object) and give it a description?
Surely there are use-cases where the controller method wants to parse the request body itself and allow anything as input, but it's quite rare and sometimes even misused.

@nickvergessen does Talk have any endpoint that needs this? I'm not aware of any such case in server, so I'd just not put any work into it, as long as there is no app that would actually benefit from it.

[nickvergessen]

https://github.com/nextcloud/spreed/blob/2dad1f76b8a17fea4eeb9e980926b57768697cca/lib/Controller/SignalingController.php#L640-L655
This would be it?