support describing response headers

[zhulijian1]

Fixes #419

In the OpenAPI Specification, response object has a headers field. (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject)

But there is no field about headers in struct ResponseError. So I can not use code to describe the response header.

type ResponseError struct {
	Code      int
	Message   string
	Model     interface{}
	IsDefault bool
}

I added the Headers field with reference to the OpenAPI Specification. And in order to maintain compatibility, I did not modify Returns method, but added a new method ReturnsWithHeaders.

[emicklei]

your change looks good to me.
unfortunately, the OpenAPI specifics are now in the go-restful package ; most of it I was able to put in the go-restful-openapi package.
However, I can imagine that the non-OpenAPI counterpart will look just like you included in the PR.
I does not make sense to come up with a different type (another name) with will have the same fields anyway.

[zhulijian1]

My aim is to achieve the ability to define response headers and automatically generate a complete swagger doc. So I need a structure to save the response header's information. But if I don't add that structure, I can not find any structure suitable for describing the response headers.
Do you have any good suggestions on what I should do to achieve my aim?

[emicklei]

@zhulijian1 no i do not. I will merge this change and make it available in v2 and v3

[zhulijian1]

thanks :)