Merge branch 'custom-header-support'

Tim Vandecasteele · Tim Vandecasteele · commit 71c5d719fea0 · 2012-09-05T13:52:06.000+02:00
diff --git a/README.markdown b/README.markdown
@@ -42,6 +42,26 @@ 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: {
+    "XAuthToken" => {
+      description: "Valdates your identity",
+      required: true 
+    },
+    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).
 
diff --git a/lib/grape-swagger.rb b/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'
+                  name = (value.is_a?(Hash) && value[:full_name]) || param
+                  {
+                    paramType: paramType,
+                    name: name,
+                    description: description,
+                    dataType: dataType,
+                    required: required
+                  }
+                end
+              else
+                []
+              end
+            end
+
+
+            def parse_header_params(params)
+              if params
+                params.map do |param, value|
+                  dataType = 'String'
+                  description = value.is_a?(Hash) ? value[:description] : ''
+                  required = value.is_a?(Hash) ? !!value[:required] : false
+                  paramType = "header"
+                  {
+                    paramType: paramType,
+                    name: param,
+                    description: description,
+                    dataType: dataType,
+                    required: required
+                  }
+                end
+              else
+                []
               end
             end
 
diff --git a/spec/grape-swagger-helper_spec.rb b/spec/grape-swagger-helper_spec.rb
@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+describe "helpers" do
+
+	before(:all) do
+		class HelperTestAPI < Grape::API
+			add_swagger_documentation
+		end
+
+		@api = Object.new
+		# after injecting grape-swagger into the Test API we get the helper methods
+		# back from the first endpoint's class (the API mounted by grape-swagger
+		# to serve the swagger_doc
+		@api.extend HelperTestAPI.endpoints.first.options[:app].helpers
+
+	end
+
+	context "parsing parameters" do
+		it "should parse params as query strings for a GET" do
+			params = {
+				name: {type: 'String', :desc => "A name", required: true },
+				level: 'max'
+			}
+			path = "/coolness"
+			method = "GET"
+			@api.parse_params(params, path, method).should ==
+			[
+				{paramType: "query", name: :name, description:"A name", dataType: "String", required: true},
+				{paramType: "query", name: :level, description:"", dataType: "String", required: false}
+			]
+		end
+
+		it "should parse params as body for a POST" do
+			params = {
+				name: {type: 'String', :desc =>"A name", required: true },
+				level: 'max'
+			}
+			path = "/coolness"
+			method = "POST"
+			@api.parse_params(params, path, method).should ==
+			[
+				{paramType: "body", name: :name, description:"A name", dataType: "String", required: true},
+				{paramType: "body", name: :level, description:"", dataType: "String", required: false}
+			]
+		end
+	end
+
+	context "parsing the path" do
+		it "should parse the path" do
+			path = ":abc/def(.:format)"
+			@api.parse_path(path, nil).should == "{abc}/def.{format}"
+		end
+
+		it "should parse the path with a specified version" do
+			path = ":abc/{version}/def(.:format)"
+			@api.parse_path(path, 'v1').should == "{abc}/v1/def.{format}"
+		end
+	end
+
+	context "parsing header parameters" do
+		it "should parse params for the header" do
+			params = {"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
diff --git a/spec/simple_mounted_api_spec.rb b/spec/simple_mounted_api_spec.rb
@@ -9,6 +9,16 @@ class SimpleMountedApi < Grape::API
       get '/simple' do
         {:bla => 'something'}
       end
+      
+      desc 'this gets something else', {
+        :headers => {
+          "XAuthToken" => {description: "A required header.", required: true}, 
+          "XOtherHeader" => {description: "An optional header.", required: false}
+        }
+      }
+      get '/simple_with_headers' do
+        {:bla => 'something_else'}
+      end
     end
 
     class SimpleApi < Grape::API
@@ -21,11 +31,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}, {:paramType=>\"header\", :name=>\"XOtherHeader\", :description=>\"An optional header.\", :dataType=>\"String\", :required=>false}]}]}]}"
+  end
 end
