Support for response header documentation

[Kek5chen]

The OpenAPI Spec includes the possibility to provide information about (custom) headers passed through the responder of a handler, in actix_web usually that resolved to a HttpResponse(Builder) object. This is probably analogous to a feature on the #[api_operation] macro.

Currently there's the use case where you would like to document information about custom headers passed in the response, and I don't see the possibility to do this in any way.

[Kek5chen]

I suppose one way would be to wrap the response in a wrapper type and manually implement Responder and ApiComponent, without using the derive macro as well.

That doesn't seem like a good intended way though for just supporting more options in the response documentation.

[rlebran]

Hey, thanks for the report.

There is currently no acceptable way to document a response header, I will have a look at it.
Keeping you updated.

[rlebran]

I see two possibilities here:

• Have another parameter like response_header = ... on the #[api_operation] macro which allow to document response header
• Have another parameter like response = ... on the #[api_operation] macro which allow to override the documentation for the response

The second one would allow to document response when the handler return an HttpResponse but might be a bit too verbose when all we want is to add a header to an already documented response.
We can possibly have both mutually exclusive.

WDYT ?

[Kek5chen]

My thoughts on the syntax went into a similar direction. Though I see a pattern here.

The produces and error_code attributes are both also part of a broader response pattern.

I think introducing all of these fields under a response field would make the api cleaner and would allow for even more future expansion in case people would like to document other response related things. For example cookies? (which also aligns pretty tight with this issue, just to keep it close mentally).

Maybe there's even more things that a response would turn opaque, and there's no proper way to make these all known since an HttpResponse object is extremely flexible and we can't inspect it later on runtime.

One extremely cursed thing that'd also be possible is to introspection the full path of any function ident in the proc macro, and extract the arguments, including any header names. But I can see how that doesn't hold stably in any way and completely disregards non-static variables passed into header insertion functions.

TLDR; I'd go with a response attribute and move response related things in there, as well as expand it in the future.