Add a little more documentation to the API DSL, properly protect some methods.

Author: Michael Bleigh

Gemfile

@@ -1,3 +1,5 @@
+source 'http://rubygems.org'
+
 gem 'rack'
 gem 'rack-mount', '~> 0.6.13'
 gem 'rack-jsonp'
@@ -9,6 +11,7 @@ gem 'multi_xml'
 group :development do
   gem 'rake'
   gem 'jeweler'
+  # gem 'yard'
 end
 
 group :test do

Gemfile.lock

@@ -1,4 +1,5 @@
 GEM
+  remote: http://rubygems.org/
   specs:
     builder (2.1.2)
     cucumber (0.8.5)

Rakefile

@@ -3,6 +3,10 @@ require 'bundler'
 
 Bundler.setup :default, :test, :development
 
+def version
+  @version ||= open('VERSION').read.trim
+end
+
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
@@ -33,12 +37,34 @@ end
 task :spec => :check_dependencies
 task :default => :spec
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "grape #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+begin
+  require 'yard'
+  YARD_OPTS = ['-m', 'markdown', '-M', 'maruku']
+  DOC_FILES = ['lib/**/*.rb', 'README.markdown']
+  
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files   = DOC_FILES
+    t.options = YARD_OPTS
+  end
+  
+  namespace :doc do
+    YARD::Rake::YardocTask.new(:pages) do |t|
+      t.files   = DOC_FILES
+      t.options = YARD_OPTS + ['-o', '../grape.doc']
+    end
+    
+    namespace :pages do
+      desc 'Generate and publish YARD docs to GitHub pages.'
+      task :publish => ['doc:pages'] do
+        Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
+          system("git add .")
+          system("git add -u")
+          system("git commit -m 'Generating docs for version #{version}.'")
+          system("git push origin gh-pages")
+        end
+      end
+    end
+  end
+rescue LoadError
+  puts "You need to install YARD."
+end

lib/grape/api.rb

@@ -1,5 +1,6 @@
 require 'rack/mount'
 require 'rack/auth/basic'
+require 'logger'
 
 module Grape
   class API
@@ -8,14 +9,18 @@ module Helpers; end
     class << self
       attr_reader :route_set
 
+      def logger
+        @logger ||= Logger.new($STDOUT)
+      end
+      
       def reset!
         @settings = [{}]
         @route_set = Rack::Mount::RouteSet.new
         @prototype = nil
       end
 
       def call(env)
-        puts "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}"
+        logger.info "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}"
         route_set.freeze.call(env)
       end
 
@@ -30,6 +35,11 @@ def settings_stack
         @settings
       end
 
+      # Set a configuration value for this
+      # namespace.
+      #
+      # @param key [Symbol] The key of the configuration variable.
+      # @param value [Object] The value to which to set the configuration variable.
       def set(key, value)
         @settings.last[key.to_sym] = value
       end
@@ -48,6 +58,9 @@ 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 
+      # serializers. Currently only `:json` is
+      # supported.
       def default_format(new_format = nil)
         new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
       end
@@ -76,6 +89,8 @@ def helpers(&block)
         end
       end
 
+      # Add an authentication type to the API. Currently
+      # only `:http_basic` is supported.
       def auth(type = nil, options = {}, &block)
         if type
           set(:auth, {:type => type.to_sym, :proc => block}.merge(options))
@@ -93,47 +108,34 @@ def http_basic(options = {}, &block)
         auth :http_basic, options, &block
       end
 
-      def route_set
-        @route_set ||= Rack::Mount::RouteSet.new
-      end
-      
-      def compile_path(path)
-        parts = []
-        parts << prefix if prefix
-        parts << ':version' if version
-        parts << namespace if namespace
-        parts << path
-        Rack::Mount::Utils.normalize_path(parts.join('/'))
-      end
-
-      def route(method, path_info, &block)
-        route_set.add_route(build_endpoint(&block), 
-          :path_info => Rack::Mount::Strexp.compile(compile_path(path_info)), 
-          :request_method => method
-        )
-      end
-      
-      def build_endpoint(&block)
-        
-        b = Rack::Builder.new
-        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
-        
-        endpoint = Grape::Endpoint.generate(&block)
-        endpoint.send :include, helpers
-        b.run endpoint
+      # 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 
+      def route(methods, paths, &block)
+        methods = Array(methods)
+        paths = ['/'] if paths == []
+        paths = Array(paths)
+        endpoint = build_endpoint(&block)
 
-        b.to_app
+        methods.each do |method|
+          paths.each do |path|
+            path = Rack::Mount::Strexp.compile(compile_path(path))
+            route_set.add_route(endpoint, 
+              :path_info => path, 
+              :request_method => (method.to_s.upcase unless method == :any)
+            )
+          end
+        end
       end
 
-      def get(path_info = '', &block); route('GET', path_info, &block) end
-      def post(path_info = '', &block); route('POST', path_info, &block) end
-      def put(path_info = '', &block); route('PUT', path_info, &block) end
-      def head(path_info = '', &block); route('HEAD', path_info, &block) end
-      def delete(path_info = '', &block); route('DELETE', path_info, &block) end
+      def get(*paths, &block); route('GET', paths, &block) end
+      def post(*paths, &block); route('POST', paths, &block) end
+      def put(*paths, &block); route('PUT', paths, &block) end
+      def head(*paths, &block); route('HEAD', paths, &block) end
+      def delete(*paths, &block); route('DELETE', paths, &block) end
 
       def namespace(space = nil, &block)
         if space || block_given?
@@ -164,9 +166,39 @@ def nest(*blocks, &block)
       alias_method :resource, :namespace
       alias_method :resources, :namespace
 
+      protected
+      
+      def build_endpoint(&block)
+        b = Rack::Builder.new
+        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
+        
+        endpoint = Grape::Endpoint.generate(&block)
+        endpoint.send :include, helpers
+        b.run endpoint
+        
+        b.to_app
+      end
+      
       def inherited(subclass)
         subclass.reset!
       end
+      
+      def route_set
+        @route_set ||= Rack::Mount::RouteSet.new
+      end
+      
+      def compile_path(path)
+        parts = []
+        parts << prefix if prefix
+        parts << ':version' if version
+        parts << namespace if namespace
+        parts << path
+        Rack::Mount::Utils.normalize_path(parts.join('/'))
+      end
     end  
 
     reset! 

spec/grape/api_spec.rb

@@ -119,7 +119,7 @@ def app; subject end
         version 'v2'
         compile_path('hello').should == '/:version/hello'
       end
-      subject.compile_path('hello').should == '/hello'
+      subject.send(:compile_path, 'hello').should == '/hello'
     end
 
     %w(group resource resources).each do |als|
@@ -149,6 +149,39 @@ def app; subject end
       last_response.body.should == 'Created a Vote'
     end
 
+    it 'should allow for multiple paths' do
+      subject.get("/abc", "/def") do
+        "foo"
+      end
+      
+      get '/abc'
+      last_response.body.should == 'foo'
+      get '/def'
+      last_response.body.should == 'foo'
+    end
+    
+    it 'should allow for multiple verbs' do
+      subject.route([:get, :post], '/abc') do
+        "hiya"
+      end
+      
+      get '/abc'
+      last_response.body.should == 'hiya'
+      post '/abc'
+      last_response.body.should == 'hiya'
+    end
+    
+    it 'should allow for :any as a verb' do
+      subject.route(:any, '/abc') do
+        "lol"
+      end
+      
+      %w(get post put delete).each do |m|
+        send(m, '/abc')
+        last_response.body.should == 'lol'
+      end
+    end
+    
     verbs = %w(post get head delete put)
     verbs.each do |verb|
       it "should allow and properly constrain a #{verb.upcase} method" do