lib/grape/api.rb in grape-0.1.1 vs lib/grape/api.rb in grape-0.1.3

@@ -43,20 +43,32 @@
       # @param value [Object] The value to which to set the configuration variable.
       def set(key, value)
         @settings.last[key.to_sym] = value
       end
       
-      # Define a root prefix for your entire
-      # API. For instance, if you had an api
-      # that you wanted to be namespaced at
-      # `/api/` you would do this:
-      # 
-      #   prefix '/api'
+      # Define a root URL prefix for your entire
+      # API.
       def prefix(prefix = nil)
         prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
       end
       
+      # Specify an API version.
+      #
+      # @example API with legacy support.
+      #   class MyAPI < Grape::API
+      #     version 'v2'
+      #     
+      #     get '/main' do
+      #       {:some => 'data'}
+      #     end
+      #         
+      #     version 'v1' do
+      #       get '/legacy' do
+      #         {:legacy => 'data'}
+      #       end
+      #     end
+      #   end
       def version(*new_versions, &block)
         new_versions.any? ? nest(block){ set(:version, new_versions) } : settings[:version]
       end
       
       # Specify the default format for the API's 
@@ -67,17 +79,18 @@
       end
 
       # Add helper methods that will be accessible from any
       # endpoint within this namespace (and child namespaces).
       #
-      #    class ExampleAPI
-      #      helpers do
-      #        def current_user
-      #          User.find_by_id(params[:token])
-      #        end
-      #      end
-      #    end
+      # @example Define some helpers.
+      #     class ExampleAPI < Grape::API
+      #       helpers do
+      #         def current_user
+      #           User.find_by_id(params[:token])
+      #         end
+      #       end
+      #     end
       def helpers(&block)
         if block_given?
           m = settings_stack.last[:helpers] || Module.new
           m.class_eval &block
           set(:helpers, m)
@@ -110,13 +123,19 @@
       end
       
       # Defines a route that will be recognized
       # by the Grape API.
       #
-      # @param methods [HTTP Verb(s)] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
-      # @param paths [String(s)] One or more strings representing the URL segment(s) for this route.
-      # @param block [Proc] The code to be executed 
+      # @param methods [HTTP Verb] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
+      # @param paths [String] One or more strings representing the URL segment(s) for this route.
+      #
+      # @example Defining a basic route.
+      #   class MyAPI < Grape::API
+      #     route(:any, '/hello') do
+      #       {:hello => 'world'}
+      #     end
+      #   end
       def route(methods, paths, &block)
         methods = Array(methods)
         paths = ['/'] if paths == []
         paths = Array(paths)
         endpoint = build_endpoint(&block)
@@ -156,11 +175,28 @@
       # 
       # @param name [Symbol] Purely placebo, just allows to to name the scope to make the code more readable.
       def scope(name = nil, &block)
         nest(block)
       end
-      
+
+      # Apply a custom middleware to the API. Applies
+      # to the current namespace and any children, but
+      # not parents.
+      #
+      # @param middleware_class [Class] The class of the middleware you'd like to inject.
+      def use(middleware_class, *args)
+        settings_stack.last[:middleware] ||= []
+        settings_stack.last[:middleware] << [middleware_class, *args]        
+      end
+
+      # Retrieve an array of the middleware classes
+      # and arguments that are currently applied to the
+      # application.
+      def middleware
+        settings_stack.inject([]){|a,s| a += s[:middleware] if s[:middleware]; a}
+      end
+
       protected
       
       # Execute first the provided block, then each of the
       # block passed in. Allows for simple 'before' setups
       # of settings stack pushes.
@@ -181,11 +217,12 @@
         b.use Grape::Middleware::Error
         b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
         b.use Grape::Middleware::Prefixer, :prefix => prefix if prefix        
         b.use Grape::Middleware::Versioner, :versions => (version if version.is_a?(Array)) if version
         b.use Grape::Middleware::Formatter, :default_format => default_format || :json
-        
+        middleware.each{|m| b.use *m }
+
         endpoint = Grape::Endpoint.generate(&block)
         endpoint.send :include, helpers
         b.run endpoint
         
         b.to_app
@@ -201,14 +238,15 @@
       
       def compile_path(path)
         parts = []
         parts << prefix if prefix
         parts << ':version' if version
-        parts << namespace if namespace
-        parts << path
+        parts << namespace.to_s if namespace
+        parts << path.to_s if path && '/' != path
+        parts.last << '(.:format)'
         Rack::Mount::Utils.normalize_path(parts.join('/'))
       end
     end  
     
     reset! 
   end
-end
\ No newline at end of file
+end