adds adding of response headers

README.md

@@ -547,24 +547,6 @@ get '/thing', http_codes: [
   ...
 end
 ```
-
-The amazon api gateway parameters can be added by indicated a aws hash with auth and integration keys, example:
-
-``` ruby
-
-desc 'thing', aws: {auth: 'aws_iam',
-                integration: {
-                  type: 'aws',
-                  uri: 'foo_bar_uri',
-                  httpMethod: 'get'
-                }
-              }
-
-get '/thing' do
-  ...
-end
-```
-
 If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L121) would be taken.
 
 The result is then something like following:
@@ -586,6 +568,42 @@ The result is then something like following:
 },
 ```
 
+### direct adding of additional swagger information
+
+- The amazon api gateway parameters can be added by indicated a aws hash with auth and integration keys, example:
+
+``` ruby
+desc 'thing',
+  aws: {
+    auth: 'aws_iam',
+    integration: {
+      type: 'aws',
+      uri: 'foo_bar_uri',
+      httpMethod: 'get'
+    }
+  }
+
+  …
+
+```
+
+- defining headers, by adding it to the desc block
+
+```ruby
+desc 'This returns something',
+  headers: {
+    "X-Rate-Limit-Limit": {
+      "description": "The number of allowed requests in the current period",
+      "type": "integer"
+    }
+  }
+
+    …
+
+```
+
+
+
 ## Contributing to grape-swagger
 
 See [CONTRIBUTING](CONTRIBUTING.md).

lib/grape-swagger/endpoint.rb

@@ -126,6 +126,7 @@ module Grape
 
       methods[:description] = route.route_desc if route.route_desc
       methods[:responses] = response_object(route)
+      methods[:headers] = route.route_headers if route.route_headers
 
       params = route.route_params
       methods[:parameters] = params_object(route)

spec/swagger_v2/api_swagger_v2_grape_master_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-describe 'support for grame master' do
+describe 'support for grape master' do
   before :all do
     module GrapeMaster
       module Entities

spec/swagger_v2/api_swagger_v2_headers_spec.rb

@@ -0,0 +1,88 @@
+require 'spec_helper'
+
+describe 'entities exposing an array' do
+  before :all do
+    module TheApi
+      module Entities
+        class ApiError < Grape::Entity
+          expose :code, documentation: { type: Integer }
+          expose :message, documentation: { type: String }
+        end
+
+        class UseHeader < Grape::Entity
+          present_collection true
+          expose :items, as: 'diagnoses', using: Entities::ApiError, documentation: { is_array: true }
+          expose :others, documentation: { type: String }
+        end
+      end
+
+      class HeadersApi < Grape::API
+        format :json
+
+        desc 'This returns something',
+          headers:  {
+            "X-Rate-Limit-Limit": {
+              "description": "The number of allowed requests in the current period",
+              "type": "integer"
+          }},
+
+          entity: Entities::UseHeader
+        get '/use_headers' do
+          { "declared_params" => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::HeadersApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  describe "it exposes a nested entity as array" do
+    specify do
+
+      expect(subject).to eql({
+        "info"=>{
+          "title"=>"API title",
+          "version"=>"v1"
+        },
+        "swagger"=>"2.0",
+        "produces"=>["application/json"],
+        "host"=>"example.org",
+        "paths"=>{
+          "/use_headers"=>{
+            "get"=>{
+              "produces"=>["application/json"],
+              "responses"=>{
+                "200"=>{
+                  "description"=>"This returns something",
+                  "schema"=>{
+                    "$ref"=>"#/definitions/UseHeader"}}},
+              "headers"=>{
+                "X-Rate-Limit-Limit"=>{
+                  "description"=>"The number of allowed requests in the current period",
+                  "type"=>"integer"
+              }}}}},
+        "definitions"=>{
+          "UseHeader"=>{
+            "type"=>"object",
+            "properties"=>{
+              "diagnoses"=>{"$ref"=>"#/definitions/ApiError"},
+              "others"=>{"type"=>"string"}
+          }},
+          "ApiError"=>{
+            "type"=>"object",
+            "properties"=>{
+              "code"=>{"type"=>"integer"},
+              "message"=>{"type"=>"string"}
+      }}}})
+    end
+  end
+end