Add ability to document response headers

[awiddersheim]

The library has the ability to quickly document the expected request headers but currently there is not greay way to document the response headers. There was some stuff added in a2b73da to be able to do it but only with error handlers.

I was thinking the best place to do it would be in response().

Seems like it might be better to convert responses to a dict rather than a tuple which has to get unpacked and makes this a bit difficult.

Perhaps this is part of the todo planned:

https://github.com/noirbizarre/flask-restplus/blob/master/flask_restplus/swagger.py#L384

[noirbizarre]

Hum, you're right.

Seems to be the@api.header is redundant with adding a RequestParser header argument.
So maybe I should use @api.header for documenting response header instead a let RequestParser expose expected headers ?

[awiddersheim]

Yeah, that makes sense to me as well. Pretty large breaking change though obviously.

[noirbizarre]

Yes, but not so big, @api.response was added late (0.8) and it's sole purpose is documenting, so it does not break the API behavoir, only the header documentation.

[defat]

I'd suggest extending api.response with headers definition instead of using separate api.header decorator thus it gives possibility for returning different headers for different response statuses.