added basic support for specifying parameters that need to be passed in the header

Author: idyll

README.markdown

@@ -42,6 +42,28 @@ You can pass a hash with some configuration possibilities to ```add_swagger_docu
 * ```:base_path``` Basepath of the API that's being exposed
 * ```:markdown``` Allow markdown in `notes`, default `false`
 
+## Swagger Header Parameters
+
+Swagger also supports the documentation of parameters passed in the header. Since grape's ```params[]``` doesn't return header parameters we can 
+to specify header parameters seperately in a block after the description.
+
+``` ruby
+desc "Return super-secret information", {
+  headers: [
+    {
+      name: "XAuthToken",
+      description: "Valdates your identity",
+      required: true 
+    },
+    {
+      name: "XOptionalHeader",
+      description: "Not reallly needed",
+      required: false 
+    }
+  ]
+}
+```
+
 ## Swagger additions
 grape-swagger allows you to add an explanation in markdown in the notes field. Which would result in proper formatted markdown in Swagger UI. The default Swagger UI doesn't allow HTML in the notes field, so you need to use an adapted version of Swagger UI (you can find one at https://github.com/tim-vandecasteele/swagger-ui/tree/vasco).
 

lib/grape-swagger.rb

@@ -87,7 +87,8 @@ def self.setup(options)
                     :summary => route.route_description || '',
                     :nickname   => route.route_method + route.route_path.gsub(/[\/:\(\)\.]/,'-'),
                     :httpMethod => route.route_method,
-                    :parameters => parse_params(route.route_params, route.route_path, route.route_method)
+                    :parameters => parse_header_params(route.route_headers) +
+                      parse_params(route.route_params, route.route_path, route.route_method)
                   }]
                 }
               end
@@ -105,19 +106,46 @@ def self.setup(options)
 
           helpers do
             def parse_params(params, path, method)
-              params.map do |param, value|
-                value[:type] = 'file' if value.is_a?(Hash) && value[:type] == 'Rack::Multipart::UploadedFile'
-                dataType = value.is_a?(Hash) ? value[:type]||'String' : 'String'
-                description = value.is_a?(Hash) ? value[:desc] : ''
-                required = value.is_a?(Hash) ? !!value[:required] : false
-                paramType = path.match(":#{param}") ? 'path' : (method == 'POST') ? 'body' : 'query'
-                {
-                  paramType: paramType,
-                  name: value[:full_name] || param,
-                  description: description,
-                  dataType: dataType,
-                  required: required
-                }
+              if params
+                params.map do |param, value|
+                  value[:type] = 'file' if value.is_a?(Hash) && value[:type] == 'Rack::Multipart::UploadedFile'
+
+                  dataType = value.is_a?(Hash) ? value[:type]||'String' : 'String'
+                  description = value.is_a?(Hash) ? value[:desc] : ''
+                  required = value.is_a?(Hash) ? !!value[:required] : false
+                  paramType = path.match(":#{param}") ? 'path' : (method == 'POST') ? 'body' : 'query'
+                  {
+                    paramType: paramType,
+                    name: value[:full_name] || param,
+                    description: description,
+                    dataType: dataType,
+                    required: required
+                  }
+                end
+              else
+                []
+              end
+            end
+
+
+            def parse_header_params(params)
+              if params
+                params.map do |details|
+                  name = details[:name]
+                  dataType = 'String'
+                  description = details[:description]
+                  required = details[:required]
+                  paramType = "header"
+                  {
+                    paramType: paramType,
+                    name: name,
+                    description: description,
+                    dataType: dataType,
+                    required: required
+                  }
+                end
+              else
+                []
               end
             end
 

spec/grape-swagger-helper_spec.rb

@@ -52,4 +52,14 @@ class HelperTestAPI < Grape::API
 		end
 	end
 
+	context "parsing header parameters" do
+		it "should parse params for the header" do
+			params = [{name: "XAuthToken", description: "A required header.", required: true}]
+			@api.parse_header_params(params).should == 
+			[	
+				{paramType: "header", name: "XAuthToken", description:"A required header.", dataType: "String", required: true}
+			]
+		end
+	end
+	
 end

spec/simple_mounted_api_spec.rb

@@ -9,6 +9,13 @@ class SimpleMountedApi < Grape::API
       get '/simple' do
         {:bla => 'something'}
       end
+      
+      desc 'this gets something else', {
+        :headers => [{name: "XAuthToken", description: "A required header.", required: true}]
+      }
+      get '/simple_with_headers' do
+        {:bla => 'something_else'}
+      end
     end
 
     class SimpleApi < Grape::API
@@ -21,11 +28,16 @@ def app; SimpleApi end
 
   it "retrieves swagger-documentation on /swagger_doc" do
     get '/swagger_doc'
-    last_response.body.should == "{:apiVersion=>\"0.1\", :swaggerVersion=>\"1.1\", :basePath=>\"http://example.org\", :operations=>[], :apis=>[{:path=>\"/swagger_doc/simple.{format}\"}, {:path=>\"/swagger_doc/swagger_doc.{format}\"}]}"
+    last_response.body.should == "{:apiVersion=>\"0.1\", :swaggerVersion=>\"1.1\", :basePath=>\"http://example.org\", :operations=>[], :apis=>[{:path=>\"/swagger_doc/simple.{format}\"}, {:path=>\"/swagger_doc/simple_with_headers.{format}\"}, {:path=>\"/swagger_doc/swagger_doc.{format}\"}]}"
   end
 
   it "retrieves the documentation for mounted-api" do
     get '/swagger_doc/simple'
     last_response.body.should == "{:apiVersion=>\"0.1\", :swaggerVersion=>\"1.1\", :basePath=>\"http://example.org\", :resourcePath=>\"\", :apis=>[{:path=>\"/simple.{format}\", :operations=>[{:notes=>\"_test_\", :summary=>\"this gets something\", :nickname=>\"GET-simple---format-\", :httpMethod=>\"GET\", :parameters=>[]}]}]}"
   end
+
+  it "retrieves the documentation for mounted-api that includes headers" do
+    get '/swagger_doc/simple_with_headers'
+    last_response.body.should == "{:apiVersion=>\"0.1\", :swaggerVersion=>\"1.1\", :basePath=>\"http://example.org\", :resourcePath=>\"\", :apis=>[{:path=>\"/simple_with_headers.{format}\", :operations=>[{:notes=>nil, :summary=>\"this gets something else\", :nickname=>\"GET-simple_with_headers---format-\", :httpMethod=>\"GET\", :parameters=>[{:paramType=>\"header\", :name=>\"XAuthToken\", :description=>\"A required header.\", :dataType=>\"String\", :required=>true}]}]}]}"
+  end
 end