grape-swagger 0.2.1 → 0.3.0

data/README.markdown

@@ -41,6 +41,27 @@ You can pass a hash with some configuration possibilities to ```add_swagger_docu
 * ```:api_version``` Version of the API that's being exposed
 * ```:base_path``` Basepath of the API that's being exposed
 * ```:markdown``` Allow markdown in `notes`, default `false`
+* ```:hide_documentation_path``` Don't show the '/swagger_doc' path in the generated swagger documentation
+
+## 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).

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/grape-swagger.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "grape-swagger"
-  s.version = "0.2.1"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tim Vandecasteele"]
-  s.date = "2012-08-17"
+  s.date = "2012-10-19"
   s.description = "A simple way to add proper auto generated documentation - that can be displayed with swagger - to your inline described grape API"
   s.email = "tim.vandecasteele@gmail.com"
   s.extra_rdoc_files = [
@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
     "VERSION",
     "grape-swagger.gemspec",
     "lib/grape-swagger.rb",
+    "spec/grape-swagger-helper_spec.rb",
     "spec/grape-swagger_spec.rb",
     "spec/non_default_api_spec.rb",
     "spec/simple_mounted_api_spec.rb",

data/lib/grape-swagger.rb

@@ -11,7 +11,7 @@ module Grape
         original_mount mounts
         @combined_routes ||= {}
         mounts::routes.each do |route|
-          resource = route.route_path.match('\/(.*?)[\.\/\(]').captures.first || '/'
+          resource = route.route_path.match('\/(\w*?)[\.\/\(]').captures.first || '/'
           @combined_routes[resource.downcase] ||= []
           @combined_routes[resource.downcase] << route
         end
@@ -41,7 +41,8 @@ module Grape
               :mount_path => '/swagger_doc',
               :base_path => nil,
               :api_version => '0.1',
-              :markdown => false
+              :markdown => false,
+              :hide_documentation_path => false
             }
             options = defaults.merge(options)
 
@@ -49,6 +50,7 @@ module Grape
             @@mount_path = options[:mount_path]
             @@class_name = options[:class_name] || options[:mount_path].gsub('/','')
             @@markdown = options[:markdown]
+            @@hide_documentation_path = options[:hide_documentation_path]
             api_version = options[:api_version]
             base_path = options[:base_path]
 
@@ -58,6 +60,10 @@ module Grape
               header['Access-Control-Request-Method'] = '*'
               routes = @@target_class::combined_routes
 
+              if @@hide_documentation_path
+                routes.reject!{ |route, value| "/#{route}/".index(parse_path(@@mount_path, nil) << '/') == 0 }
+              end
+
               routes_array = routes.keys.map do |route|
                   { :path => "#{@@mount_path}/#{route}.{format}" }
               end
@@ -81,13 +87,14 @@ module Grape
               routes_array = routes.map do |route|
                 notes = route.route_notes && @@markdown ? Kramdown::Document.new(route.route_notes.strip_heredoc).to_html : route.route_notes
                 {
-                  :path => parse_path(route.route_path),
+                  :path => parse_path(route.route_path, api_version),
                   :operations => [{
                     :notes => notes,
                     :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,28 +112,61 @@ module Grape
 
           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'
+              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
 
-                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: param,
-                  description: description,
-                  dataType: dataType,
-                  required: required
-                }
+
+            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
 
-            def parse_path(path)
+            def parse_path(path, version)
               # adapt format to swagger format
               parsed_path = path.gsub('(.:format)', '.{format}')
-              # adapt params to swagger format
-              parsed_path.gsub(/:([a-z]+)/, '{\1}')
+              # This is attempting to emulate the behavior of 
+              # Rack::Mount::Strexp. We cannot use Strexp directly because 
+              # all it does is generate regular expressions for parsing URLs. 
+              # TODO: Implement a Racc tokenizer to properly generate the 
+              # parsed path.
+              parsed_path = parsed_path.gsub(/:([a-zA-Z_]\w*)/, '{\1}')
+              # add the version
+              parsed_path = parsed_path.gsub('{version}', version) if version
+              parsed_path
             end
           end
         end
@@ -140,7 +180,7 @@ class Object
   #   @person ? @person.name : nil
   # vs
   #   @person.try(:name)
-  # 
+  #
   # File activesupport/lib/active_support/core_ext/object/try.rb#L32
    def try(*a, &b)
     if a.empty? && block_given?

data/spec/grape-swagger-helper_spec.rb

@@ -0,0 +1,88 @@
+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 a path that has vars with underscores in the name" do
+      path = "abc/:def_g(.:format)"
+			@api.parse_path(path, nil).should == "abc/{def_g}.{format}"
+      
+    end
+
+    it "should parse a path that has vars with numbers in the name" do
+      path = "abc/:sha1(.:format)"
+			@api.parse_path(path, nil).should == "abc/{sha1}.{format}"
+    end
+
+    it "should parse a path that has multiple variables" do
+      path1 = "abc/:def/:geh(.:format)"
+      path2 = "abc/:def:geh(.:format)"
+			@api.parse_path(path1, nil).should == "abc/{def}/{geh}.{format}"
+			@api.parse_path(path2, nil).should == "abc/{def}{geh}.{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

data/spec/non_default_api_spec.rb

@@ -61,6 +61,29 @@ describe "options: " do
     end
   end
 
+  context "overruling hiding the documentation paths" do
+    before(:all) do
+      class HideDocumentationPathMountedApi < Grape::API
+        desc 'this gets something'
+        get '/something' do
+          {:bla => 'something'}
+        end
+      end
+
+      class SimpleApiWithHiddenDocumentation < Grape::API
+        mount HideDocumentationPathMountedApi
+        add_swagger_documentation :hide_documentation_path => true
+      end
+    end
+
+    def app; SimpleApiWithHiddenDocumentation end
+
+    it "it doesn't show the documentation path 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/something.{format}\"}]}" 
+    end
+  end
+
   context "overruling the mount-path" do
     before(:all) do
       class DifferentMountMountedApi < Grape::API
@@ -120,5 +143,32 @@ describe "options: " do
       last_response.body.should == "{:apiVersion=>\"0.1\", :swaggerVersion=>\"1.1\", :basePath=>\"http://example.org\", :resourcePath=>\"\", :apis=>[{:path=>\"/something.{format}\", :operations=>[{:notes=>\"<p><em>test</em></p>\\n\", :summary=>\"this gets something\", :nickname=>\"GET-something---format-\", :httpMethod=>\"GET\", :parameters=>[]}]}]}"
     end
   end
+  
+  context "versioned API" do
+    before(:all) do
+      class VersionedMountedApi < Grape::API
+        prefix 'api'
+        version 'v1'
+  
+        desc 'this gets something'
+        get '/something' do
+          {:bla => 'something'}
+        end
+      end
+  
+      class SimpleApiWithVersion < Grape::API
+        mount VersionedMountedApi
+        add_swagger_documentation :api_version => "v1"
+      end
+    end
+  
+    def app; SimpleApiWithVersion end
+  
+    it "parses version and places it in the path" do
+      get '/swagger_doc/api'
+      last_response.body.should == "{:apiVersion=>\"v1\", :swaggerVersion=>\"1.1\", :basePath=>\"http://example.org\", :resourcePath=>\"\", :apis=>[{:path=>\"/api/v1/something.{format}\", :operations=>[{:notes=>nil, :summary=>\"this gets something\", :nickname=>\"GET-api--version-something---format-\", :httpMethod=>\"GET\", :parameters=>[]}]}]}"
+    end
+  end
+
 
 end

data/spec/simple_mounted_api_spec.rb

@@ -9,6 +9,16 @@ describe "a simple mounted api" do
       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 @@ describe "a simple mounted api" do
 
   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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-17 00:00:00.000000000 Z
+date: 2012-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -174,6 +174,7 @@ files:
 - VERSION
 - grape-swagger.gemspec
 - lib/grape-swagger.rb
+- spec/grape-swagger-helper_spec.rb
 - spec/grape-swagger_spec.rb
 - spec/non_default_api_spec.rb
 - spec/simple_mounted_api_spec.rb
@@ -193,7 +194,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3173865515529886165
+      hash: 3307258424823840533
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: