Merge pull request ruby-grape#94 from dblock/frontier-desc-api

frontier: added support for desc blocks

Author: Michael Bleigh

.gitignore

@@ -11,6 +11,9 @@ tmtags
 \#*
 .\#*
 
+## REDCAR
+.redcar
+
 ## VIM
 *.swp
 
@@ -23,7 +26,5 @@ pkg
 .yardoc/*
 dist
 Gemfile.lock
-*.orig
-*.rej
 
 ## PROJECT::SPECIFIC

README.markdown

@@ -248,32 +248,40 @@ describe Twitter::API do
 end
 ```
 
-## Inspecting an API
+## Describing and Inspecting an API
 
-Grape exposes arrays of API versions and compiled routes. Each route contains a `route_prefix`, `route_version`, `route_namespace`, `route_method`, `route_path` and `route_params`.
+Grape lets you add a description to an API along with any other optional elements that can also be inspected at runtime. 
+This can be useful for generating documentation.
 
 ```ruby
 class TwitterAPI < Grape::API
 
   version 'v1'
+
+  desc "Retrieves the API version number."
   get "version" do
     api.version
   end
 
-  version 'v2'
-  namespace "ns" do
-    get "version" do
-      api.version
-    end
+  desc "Reverses a string.", { :params =>  
+    { "s" => { :desc => "string to reverse", :type => "string" }}
+  }
+  get "reverse" do
+    params[:s].reverse
   end
 end
+```
+
+Grape then exposes arrays of API versions and compiled routes. Each route contains a `route_prefix`, `route_version`, `route_namespace`, `route_method`, `route_path` and `route_params`. The description and the optional hash that follows the API path may contain any number of keys and its values are also accessible via dynamically-generated `route_[name]` functions.
 
+```ruby
 TwitterAPI::versions # yields [ 'v1', 'v2' ]
 TwitterAPI::routes # yields an array of Grape::Route objects
 TwitterAPI::routes[0].route_version # yields 'v1'
+TwitterAPI::routes[0].route_description # yields [ { "s" => { :desc => "string to reverse", :type => "string" }} ]
 ```
 
-Grape also supports storing additional parameters with the route information. This can be useful for generating documentation. The optional hash that follows the API path may contain any number of keys and its values are also accessible via a dynamically-generated `route_[name]` function.
+Parameters can also be tagged to the method declaration itself.
 
 ```ruby
 class StringAPI < Grape::API

lib/grape/api.rb

@@ -31,6 +31,7 @@ def reset!
         @route_set = Rack::Mount::RouteSet.new
         @endpoints = []
         @mountings = []
+        @routes = nil
       end
 
       def compile
@@ -103,6 +104,11 @@ def version(*args, &block)
           end
         end
       end
+      
+      # Add a description to the next namespace or function.
+      def desc(description, options = {})
+        @last_description = options.merge({description: description})
+      end
 
       # Specify the default format for the API's
       # serializers. Currently only `:json` is
@@ -260,11 +266,13 @@ def mount(mounts)
       #     end
       #   end
       def route(methods, paths = ['/'], route_options = {}, &block)
-        endpoints << Grape::Endpoint.new(settings.clone, {
+        endpoint_options = {
           :method => methods,
           :path => paths,
-          :route_options => (route_options || {})
-        }, &block)
+          :route_options => (route_options || {}).merge(@last_description || {})
+        }
+        endpoints << Grape::Endpoint.new(settings.clone, endpoint_options, &block)
+        @last_description = nil
       end
 
       def before(&block)
@@ -326,11 +334,11 @@ def middleware
       def routes
         @routes ||= prepare_routes
       end
-
+      
       def versions
         @versions ||= []
       end
-
+      
       protected
 
       def prepare_routes

lib/grape/endpoint.rb

@@ -25,7 +25,7 @@ def initialize(settings, options = {}, &block)
 
       options[:route_options] ||= {}
     end
-    
+
     def routes
       @routes ||= prepare_routes
     end
@@ -50,8 +50,13 @@ def prepare_routes
           prepared_path = prepare_path(path)
           path = compile_path(prepared_path, !options[:app])
           regex = Rack::Mount::RegexpWithNamedGroups.new(path)
-          path_params = regex.named_captures.map { |nc| nc[0] } - [ 'version', 'format' ]
-          path_params |= (options[:route_options][:params] || [])
+          path_params = {}
+          # named parameters in the api path
+          named_params = regex.named_captures.map { |nc| nc[0] } - [ 'version', 'format' ]
+          named_params.each { |named_param| path_params[named_param] = "" }
+          # route parameters declared via desc or appended to the api declaration
+          route_params = (options[:route_options][:params] || {})
+          path_params.merge!(route_params)
           request_method = (method.to_s.upcase unless method == :any)
           routes << Route.new(options[:route_options].clone.merge({
             :prefix => settings[:root_prefix],

spec/grape/api_spec.rb

@@ -58,7 +58,7 @@ def app; subject end
     end
 
     it 'should route if any media type is allowed' do
-
+      
     end
   end
 
@@ -123,7 +123,7 @@ def app; subject end
       get '/members/23'
       last_response.body.should == "23"
     end
-
+    
     it 'should be callable with nil just to push onto the stack' do
       subject.namespace do
         version 'v2', :using => :path
@@ -136,7 +136,7 @@ def app; subject end
       get '/hello'
       last_response.body.should == "outer"
     end
-
+    
     %w(group resource resources segment).each do |als|
       it "`.#{als}` should be an alias" do
         subject.send(als, :awesome) do
@@ -231,7 +231,7 @@ def app; subject end
       subject.route([:get, :post], '/:id/first') do
         "first"
       end
-
+      
       subject.route([:get, :post], '/:id') do
         "ola"
       end
@@ -342,7 +342,7 @@ def app; subject end
       last_response.headers['Content-Type'].should eql 'application/json'
     end
   end
-
+  
   context 'custom middleware' do
     class PhonyMiddleware
       def initialize(app, *args)
@@ -374,7 +374,7 @@ def call(env)
           {:middleware => [[PhonyMiddleware, 'foo']]}
         ]
         subject.stub!(:settings).and_return(settings)
-
+  
         subject.middleware.should eql [
           [PhonyMiddleware, 123],
           [PhonyMiddleware, 'abc'],
@@ -579,7 +579,7 @@ def hello
       subject.get '/def' do
         'def'
       end
-
+      
       get '/new/abc'
       last_response.status.should eql 404
       get '/legacy/abc'
@@ -758,26 +758,103 @@ class TwitterAPI < Grape::API
     end
     describe "api structure with additional parameters" do
       before(:each) do
-        subject.get 'split/:string', { :params => [ "token" ], :optional_params => [ "limit" ] } do
-           params[:string].split(params[:token], (params[:limit] || 0).to_i)
+        subject.get 'split/:string', { :params => { "token" => "a token" }, :optional_params => { "limit" => "the limit" } } do 
+          params[:string].split(params[:token], (params[:limit] || 0).to_i)
         end
       end
       it "should split a string" do
-         get "/split/a,b,c.json", :token => ','
-         last_response.body.should == '["a","b","c"]'
+        get "/split/a,b,c.json", :token => ','
+        last_response.body.should == '["a","b","c"]'
       end
       it "should split a string with limit" do
-         get "/split/a,b,c.json", :token => ',', :limit => '2'
-         last_response.body.should == '["a","b,c"]'
+        get "/split/a,b,c.json", :token => ',', :limit => '2'
+        last_response.body.should == '["a","b,c"]'
       end
       it "should set route_params" do
-         subject.routes.size.should == 1
-         subject.routes[0].route_params.should == [ "string", "token" ]
-         subject.routes[0].route_optional_params.should == [ "limit" ]
+        subject.routes.size.should == 1
+        subject.routes[0].route_params.should == { "string" => "", "token" => "a token" }
+        subject.routes[0].route_optional_params.should == { "limit" => "the limit" }
       end
     end
   end
 
+  context "desc" do
+    describe "empty api structure" do
+      it "returns an empty array of routes" do
+        subject.desc "grape api"
+        subject.routes.should == []
+      end
+    end     
+    describe "single method with a desc" do
+      before(:each) do
+        subject.desc "ping method"
+        subject.get :ping do 
+          'pong'
+        end
+      end
+      it "returns route description" do
+        subject.routes[0].route_description.should == "ping method"
+      end
+    end    
+    describe "single method with a an array of params and a desc hash block" do
+      before(:each) do
+        subject.desc "ping method", { :params => { "x" => "y" } }
+        subject.get "ping/:x" do 
+          'pong'
+        end
+      end
+      it "returns route description" do
+        subject.routes[0].route_description.should == "ping method"
+      end
+    end    
+    describe "api structure with multiple methods and descriptions" do
+      before(:each) do
+        class JitterAPI < Grape::API
+          desc "first method"
+          get "first" do; end
+          get "second" do; end
+          desc "third method"
+          get "third" do; end
+        end
+      end
+      it "should return a description for the first method" do
+        JitterAPI::routes[0].route_description.should == "first method"
+        JitterAPI::routes[1].route_description.should be_nil
+        JitterAPI::routes[2].route_description.should == "third method"
+      end
+    end
+    describe "api structure with multiple methods, namespaces, descriptions and options" do
+      before(:each) do
+        class LitterAPI < Grape::API
+          desc "first method"
+          get "first" do; end
+          get "second" do; end
+          namespace "ns" do
+            desc "ns second", :foo => "bar"
+            get "second" do; end
+          end
+          desc "third method", :details => "details of third method"
+          get "third" do; end
+          desc "Reverses a string.", { :params =>
+            { "s" => { :desc => "string to reverse", :type => "string" }}
+          }
+          get "reverse" do
+            params[:s].reverse
+          end
+        end
+      end
+      it "should return a description for the first method" do
+        LitterAPI::routes[0].route_description.should == "first method"
+        LitterAPI::routes[1].route_description.should be_nil
+        LitterAPI::routes[2].route_description.should == "ns second"
+        LitterAPI::routes[2].route_foo.should == "bar"
+        LitterAPI::routes[3].route_description.should == "third method"
+        LitterAPI::routes[4].route_description.should == "Reverses a string."
+        LitterAPI::routes[4].route_params.should == { "s" => { :desc => "string to reverse", :type => "string" }}
+      end
+    end
+  end
+  
   describe ".rescue_from klass, block" do
     it 'should rescue Exception' do
       subject.rescue_from RuntimeError do |e|
@@ -850,12 +927,12 @@ class CommunicationError < RuntimeError; end
 
   describe '.mount' do
     let(:mounted_app){ lambda{|env| [200, {}, ["MOUNTED"]]} }
-
+  
     context 'with a bare rack app' do
       before do
         subject.mount mounted_app => '/mounty'
       end
-
+    
       it 'should make a bare Rack app available at the endpoint' do
         get '/mounty'
         last_response.body.should == 'MOUNTED'
@@ -867,7 +944,7 @@ class CommunicationError < RuntimeError; end
       end
 
       it 'should be able to cascade' do
-        subject.mount lambda{ |env|
+        subject.mount lambda{ |env| 
           headers = {}
           headers['X-Cascade'] == 'pass' unless env['PATH_INFO'].include?('boo')
           [200, headers, ["Farfegnugen"]]