[feature] Support response headers

[happyDemon]

I was sad to find out that response headers were not yet supported by scramble, so I created this POC PR to implement them.

I say POC, because my implementation feels a bit hack-y. I'm open to any feedback before I add tests.

OpenAPI 3.0 supports response headers: https://swagger.io/docs/specification/v3_0/describing-responses/#response-headers. One gotacho: response headers need to be defined on each response individually

Sample case

Laravel's ratelimiter adds the X-Ratelimit-Limit and X-Ratelimit-Remaining headers to all requests that implement the throttle middleware. When the rate limit is hit, the 429 response will also include the X-Ratelimit-Remaining header.

For a personal case, I wanted to add a X-Trace-Id header on requests that fail, so implementers of my API have something to contact support with.

Implementation

On controller method level, a developer can add #[BodyHeader(string $name, ?string $description = null, ?string $type = null, ?string $format = null)] -> I hacked something together so the header(s) get added to the response.

In withOperationTransformers it's possible to add/modify responses, adding headers on a response by calling registerHeader(string $name, ?string $description, Type $type)

Todo

• [ ] cleanup/implement the hacky logic correctly
• [ ] support laravel rate limit headers out of the box when the throttle:* middleware is applied
• [ ] add tests

[happyDemon]

ah, this PR broke some stuff. I also did some reading, seems like the BodyHeader parameter approach is not correct, I'll definitely have to rework this.

[romalytvynenko]

Hey @happyDemon

Thanks for the PR. I will add it but I need more time thinking it out. Manual response headers documentation is the part of a bigger problem: manual responses documentation. It needs a lot of focus and attention to make it right.

As of now you can simply create your own operation transformer and keep this logic there so it works for you.