Added feature to report header params in params block

[wleeper]

What's this PR do, and where should I start?

This PR address Issue #391

This PR changes the behavior by no longer output a header tag at the root level of an endpoint, and replaces that with parameters tagged with "in": "header", which is the correct Swagger 2.0 method.

See changes to spec/swagger_v2/simple_mounted_api_spec.rb to see how the behavior changed.

How should this be manually tested?

Fire up the example app and add some header variables using the proper grape syntax (note the example below is <= 0.14, not what is in the docs for 0.16.2:

        desc 'This returns something',
          failure: [{code: 400, model: Entities::ApiError}],
          headers:  {
            "X-Rate-Limit-Limit" => {
              "description" => "The number of allowed requests in the current period",
              "type" => "integer"
          }}
        get '/use_headers' do
          { "declared_params" => declared(params) }
        end

Any background context you want to provide?

Ran into this issue when I tried to add header params to our app.

[LeFnord]

@wleeper thanks for it, but to be consistent with your own proposal, I suggest a stronger distinction between request and response

1. request related: all what is inside the params block
2. response related: all from desc section

what did you mean?

[LeFnord]

👍 but the question is, how to differ between stuff for request and stuff for response …

what are your thoughts?

[wleeper]

This just addresses the request parameters. I'm not even sure exactly where swagger puts response headers and how we would capture the documentation.

[LeFnord]

yeap, I know … swagger puts the response headers into the response object,
but how can we document it?

the header key from desc is now a parameter, that was the intention for my proposal above