apipie-rails 0.2.6 → 0.3.0

data/lib/apipie/method_description.rb

@@ -5,12 +5,13 @@ module Apipie
 
     class Api
 
-      attr_accessor :short_description, :path, :http_method, :options
+      attr_accessor :short_description, :path, :http_method, :from_routes, :options
 
       def initialize(method, path, desc, options)
         @http_method = method.to_s
         @path = path
         @short_description = desc
+        @from_routes = options[:from_routes]
         @options = options
       end
 
@@ -104,7 +105,10 @@ module Apipie
     end
 
     def create_api_url(api)
-      path = "#{@resource._api_base_url}#{api.path}"
+      path = api.path
+      unless api.from_routes
+        path = "#{@resource._api_base_url}#{path}"
+      end
       path = path[0..-2] if path[-1..-1] == '/'
       return path
     end
@@ -174,7 +178,9 @@ module Apipie
     end
 
     def format_example(ex)
-      example = "#{ex[:verb]} #{ex[:path]}"
+      example = ""
+      example << "// #{ex[:title]}\n" if ex[:title].present?
+      example << "#{ex[:verb]} #{ex[:path]}"
       example << "?#{ex[:query]}" unless ex[:query].blank?
       example << "\n" << format_example_data(ex[:request_data]).to_s if ex[:request_data]
       example << "\n" << ex[:code].to_s

data/lib/apipie/routes_formatter.rb

@@ -0,0 +1,33 @@
+module Apipie
+  class RoutesFormatter
+    API_METHODS = %w{GET POST PUT PATCH OPTIONS DELETE}
+
+    # The entry method called by Apipie to extract the array
+    # representing the api dsl from the routes definition.
+    def format_routes(rails_routes, args)
+      rails_routes.map { |rails_route| format_route(rails_route, args) }
+    end
+
+    def format_route(rails_route, args)
+      { :path => format_path(rails_route),
+        :verb => format_verb(rails_route),
+        :desc => args[:desc],
+        :options => args[:options] }
+    end
+
+    def format_path(rails_route)
+      rails_route.path.spec.to_s.gsub('(.:format)', '')
+    end
+
+    def format_verb(rails_route)
+      verb = API_METHODS.select{|defined_verb| defined_verb =~ /\A#{rails_route.verb}\z/}
+      if verb.count != 1
+        verb = API_METHODS.select{|defined_verb| defined_verb == rails_route.constraints[:method]}
+        if verb.blank?
+          raise "Unknow verb #{rails_route.path.spec.to_s}"
+        end
+      end
+      verb.first
+    end
+  end
+end

data/lib/apipie/validator.rb

@@ -407,6 +407,10 @@ module Apipie
         end
       end
 
+      def expected_type
+        'boolean'
+      end
+
       def description
         "Must be 'true' or 'false'"
       end
@@ -444,6 +448,10 @@ module Apipie
         self.new(param_description, block, options[:param_group]) if block.is_a?(Proc) && block.arity <= 0 && argument == Array
       end
 
+      def expected_type
+        'array'
+      end
+
       def description
         "Must be an Array of nested elements"
       end

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = '0.2.6'
+  VERSION = '0.3.0'
 end

data/lib/tasks/apipie.rake

@@ -68,6 +68,8 @@ namespace :apipie do
         puts "#{Time.now} | Processing docs for #{lang}"
         cache_dir = ENV["OUT"] || Apipie.configuration.cache_dir
         subdir = Apipie.configuration.doc_base_url.sub(/\A\//,"")
+        subdir_levels = subdir.split('/').length
+        subdir_traversal_prefix = '../' * subdir_levels
         file_base = File.join(cache_dir, Apipie.configuration.doc_base_url)
 
         if generate_index
@@ -78,15 +80,15 @@ namespace :apipie do
         end
         Apipie.available_versions.each do |version|
           file_base_version = File.join(file_base, version)
-          Apipie.url_prefix = "../#{subdir}"
+          Apipie.url_prefix = "#{subdir_traversal_prefix}#{subdir}"
           doc = Apipie.to_json(version, nil, nil, lang)
           doc[:docs][:link_extension] = (lang ? ".#{lang}.html" : ".html")
 
           generate_index_page(file_base_version, doc, true, true, lang) if generate_index
           if generate_resources
-            Apipie.url_prefix = "../../#{subdir}"
+            Apipie.url_prefix = "../#{subdir_traversal_prefix}#{subdir}"
             generate_resource_pages(version, file_base_version, doc, true, lang)
-            Apipie.url_prefix = "../../../#{subdir}"
+            Apipie.url_prefix = "../../#{subdir_traversal_prefix}#{subdir}"
             generate_method_pages(version, file_base_version, doc, true, lang)
           end
         end

data/spec/controllers/users_controller_spec.rb

@@ -30,6 +30,7 @@ describe UsersController do
     it "should contain all resource methods" do
       methods = subject._methods
       methods.keys.should include(:show)
+      methods.keys.should include(:create_route)
       methods.keys.should include(:index)
       methods.keys.should include(:create)
       methods.keys.should include(:update)
@@ -74,233 +75,287 @@ describe UsersController do
 
     end
 
-    context "only presence validations are enabled" do
-      before do
-        Apipie.configuration.validate = true
-        Apipie.configuration.validate_value = false
-        Apipie.configuration.validate_presence = true
-      end
-
-      it "should reply to valid request" do
-        lambda { get :show, :id => 5, :session => "secret_hash" }.should_not raise_error
-        assert_response :success
+    context "validations are enabled" do
+      def reload_controllers
+        controllers_dirname = File.expand_path('../dummy/app/controllers', File.dirname(__FILE__))
+        Dir.glob("#{controllers_dirname}/**/*") { |file| load(file) if File.file?(file) }
       end
 
-      it "should fail if required parameter is missing" do
-        lambda { get :show, :id => 5 }.should raise_error(Apipie::ParamMissing, /\bsession\b/)
-      end
+      shared_examples "validates correctly" do
 
-      it "should pass if required parameter has wrong type" do
-        lambda { get :show, :id => 5, :session => "secret_hash" }.should_not raise_error
-        lambda { get :show, :id => "ten", :session => "secret_hash" }.should_not raise_error
-      end
+        context "only presence validations are enabled" do
+          before do
+            Apipie.configuration.validate_value = false
+            Apipie.configuration.validate_presence = true
+            Apipie.configuration.validate_key = false
+          end
 
-    end
+          it "should reply to valid request" do
+            lambda { get :show, :id => 5, :session => "secret_hash" }.should_not raise_error
+            assert_response :success
+          end
 
+          it "should fail if required parameter is missing" do
+            lambda { get :show, :id => 5 }.should raise_error(Apipie::ParamMissing, /\bsession\b/)
+          end
 
-    context "validations are enabled" do
-      before do
-        Apipie.configuration.validate = true
-        Apipie.configuration.validate_value = true
-        Apipie.configuration.validate_presence = true
-      end
+          it "should pass if required parameter has wrong type" do
+            lambda { get :show, :id => 5, :session => "secret_hash" }.should_not raise_error
+            lambda { get :show, :id => "ten", :session => "secret_hash" }.should_not raise_error
+          end
 
-      it "should reply to valid request" do
-        get :show, :id => '5', :session => "secret_hash"
-        assert_response :success
-      end
+        end
 
-      it "should work with nil value for a required hash param" do
-        expect {
-          get :show, :id => '5', :session => "secret_hash", :hash_param => {:dummy_hash => nil}
-        }.to raise_error(Apipie::ParamInvalid, /dummy_hash/)
-        assert_response :success
-      end
+        context "key validations are enabled" do
+          before do
+            Apipie.configuration.validate_value = false
+            Apipie.configuration.validate_presence = true
+            Apipie.configuration.validate_key = true
+          end
 
-      it "should fail if required parameter is missing" do
-        lambda { get :show, :id => 5 }.should raise_error(Apipie::ParamMissing, /\bsession\b/)
-      end
+          it "should reply to valid request" do
+            lambda { get :show, :id => 5, :session => "secret_hash" }.should_not raise_error
+            assert_response :success
+          end
 
-      it "should work with custom Type validator" do
-        lambda {
-          get :show,
-              :id => "not a number",
-              :session => "secret_hash"
-        }.should raise_error(Apipie::ParamError, /id/) # old-style error rather than ParamInvalid
-      end
+          it "should fail if extra parameter is passed in" do
+            lambda { get :show, :id => 5, :session => "secret_hash", :badparam => 'badfoo' }.should raise_error(Apipie::UnknownParam, /\bbadparam\b/)
+          end
+        end
 
-      it "should work with Regexp validator" do
-        get :show,
-            :id => 5,
-            :session => "secret_hash",
-            :regexp_param => "24 years"
-        assert_response :success
+        context "presence and value validations are enabled" do
+          before do
+            Apipie.configuration.validate_value = true
+            Apipie.configuration.validate_presence = true
+            Apipie.configuration.validate_key = false
+          end
 
-        lambda {
-          get :show,
-              :id => 5,
-              :session => "secret_hash",
-              :regexp_param => "ten years"
-        }.should raise_error(Apipie::ParamInvalid, /regexp_param/)
-      end
+          it "should reply to valid request" do
+            get :show, :id => '5', :session => "secret_hash"
+            assert_response :success
+          end
 
-      it "should work with Array validator" do
-        get :show, :id => 5, :session => "secret_hash", :array_param => "one"
-        assert_response :success
-        get :show, :id => 5, :session => "secret_hash", :array_param => "two"
-        assert_response :success
-        get :show, :id => 5, :session => "secret_hash", :array_param => '1'
-        assert_response :success
-        get :show, :id => 5, :session => "secret_hash", :boolean_param => false
-        assert_response :success
+          it "should work with nil value for a required hash param" do
+            expect {
+              get :show, :id => '5', :session => "secret_hash", :hash_param => {:dummy_hash => nil}
+            }.to raise_error(Apipie::ParamInvalid, /dummy_hash/)
+            assert_response :success
+          end
 
-        lambda {
-          get :show,
-              :id => 5,
-              :session => "secret_hash",
-              :array_param => "blabla"
-        }.should raise_error(Apipie::ParamInvalid, /array_param/)
-
-        lambda {
-          get :show,
-              :id => 5,
-              :session => "secret_hash",
-              :array_param => 3
-        }.should raise_error(Apipie::ParamInvalid, /array_param/)
-      end
+          it "should fail if required parameter is missing" do
+            lambda { get :show, :id => 5 }.should raise_error(Apipie::ParamMissing, /\bsession\b/)
+          end
 
-      it "should work with Proc validator" do
-        lambda {
-          get :show,
-              :id => 5,
-              :session => "secret_hash",
-              :proc_param => "asdgsag"
-        }.should raise_error(Apipie::ParamInvalid, /proc_param/)
-
-        get :show,
-            :id => 5,
-            :session => "secret_hash",
-            :proc_param => "param value"
-        assert_response :success
-      end
+          it "should work with custom Type validator" do
+            lambda {
+              get :show,
+                  :id => "not a number",
+                  :session => "secret_hash"
+            }.should raise_error(Apipie::ParamError, /id/) # old-style error rather than ParamInvalid
+          end
 
-      it "should work with Hash validator" do
-        post :create, :user => { :name => "root", :pass => "12345", :membership => "standard" }
-        assert_response :success
+          it "should work with Regexp validator" do
+            get :show,
+                :id => 5,
+                :session => "secret_hash",
+                :regexp_param => "24 years"
+            assert_response :success
 
-        a = Apipie[UsersController, :create]
-        param = a.params_ordered.select {|p| p.name == :user }
-        param.count.should == 1
-        param.first.validator.class.should eq(Apipie::Validator::HashValidator)
-        hash_params = param.first.validator.params_ordered
-        hash_params.count.should == 4
-        hash_params[0].name == :name
-        hash_params[1].name == :pass
-        hash_params[2].name == :membership
-
-        lambda {
-          post :create, :user => { :name => "root", :pass => "12345", :membership => "____" }
-        }.should raise_error(Apipie::ParamInvalid, /membership/)
-
-        lambda {
-          post :create, :user => { :name => "root" }
-        }.should raise_error(Apipie::ParamMissing, /pass/)
-
-        lambda {
-          post :create, :user => "a string is not a hash"
-        }.should raise_error(Apipie::ParamInvalid, /user/)
-
-        post :create, :user => { :name => "root", :pass => "pwd" }
-        assert_response :success
-      end
+            lambda {
+              get :show,
+                  :id => 5,
+                  :session => "secret_hash",
+                  :regexp_param => "ten years"
+            }.should raise_error(Apipie::ParamInvalid, /regexp_param/)
+          end
 
-      it "should support Hash validator without specifying keys" do
-        params = Apipie[UsersController, :create].to_json[:params]
-        params.should include(:name => "facts",
-                              :full_name => "facts",
-                              :validator => "Must be Hash",
-                              :description => "\n<p>Additional optional facts about the user</p>\n",
-                              :required => false,
-                              :allow_nil => true,
-                              :metadata => nil,
-                              :show => true,
-                              :expected_type => "hash")
-      end
+          it "should work with Array validator" do
+            get :show, :id => 5, :session => "secret_hash", :array_param => "one"
+            assert_response :success
+            get :show, :id => 5, :session => "secret_hash", :array_param => "two"
+            assert_response :success
+            get :show, :id => 5, :session => "secret_hash", :array_param => '1'
+            assert_response :success
+            get :show, :id => 5, :session => "secret_hash", :boolean_param => false
+            assert_response :success
 
-      it "should allow nil when allow_nil is set to true" do
-        post :create,
-             :user => {
-               :name => "root",
-               :pass => "12345",
-               :membership => "standard",
-             },
-             :facts => nil
-        assert_response :success
-      end
+            lambda {
+              get :show,
+                  :id => 5,
+                  :session => "secret_hash",
+                  :array_param => "blabla"
+            }.should raise_error(Apipie::ParamInvalid, /array_param/)
 
-      describe "nested elements"  do
+            lambda {
+              get :show,
+                  :id => 5,
+                  :session => "secret_hash",
+                  :array_param => 3
+            }.should raise_error(Apipie::ParamInvalid, /array_param/)
+          end
 
-        context "with valid input" do
-          it "should succeed" do
-            put :update,
-                {
+          it "should work with Proc validator" do
+            lambda {
+              get :show,
                   :id => 5,
-                  :user => {
-                    :name => "root",
-                    :pass => "12345"
-                  },
-                  :comments => [
-                    {
-                      :comment => 'comment1'
-                    },
-                    {
-                      :comment => 'comment2'
-                    }
-                  ]
-                }
+                  :session => "secret_hash",
+                  :proc_param => "asdgsag"
+            }.should raise_error(Apipie::ParamInvalid, /proc_param/)
 
+            get :show,
+                :id => 5,
+                :session => "secret_hash",
+                :proc_param => "param value"
             assert_response :success
           end
-        end
-        context "with bad input" do
-          it "should raise an error" do
-            expect{
-              put :update,
-                {
-                  :id => 5,
-                  :user => {
-                    :name => "root",
-                    :pass => "12345"
-                  },
-                  :comments => [
+
+          it "should work with Hash validator" do
+            post :create, :user => { :name => "root", :pass => "12345", :membership => "standard" }
+            assert_response :success
+
+            a = Apipie[UsersController, :create]
+            param = a.params_ordered.select {|p| p.name == :user }
+            param.count.should == 1
+            param.first.validator.class.should eq(Apipie::Validator::HashValidator)
+            hash_params = param.first.validator.params_ordered
+            hash_params.count.should == 4
+            hash_params[0].name == :name
+            hash_params[1].name == :pass
+            hash_params[2].name == :membership
+
+            lambda {
+              post :create, :user => { :name => "root", :pass => "12345", :membership => "____" }
+            }.should raise_error(Apipie::ParamInvalid, /membership/)
+
+            lambda {
+              post :create, :user => { :name => "root" }
+            }.should raise_error(Apipie::ParamMissing, /pass/)
+
+            lambda {
+              post :create, :user => "a string is not a hash"
+            }.should raise_error(Apipie::ParamInvalid, /user/)
+
+            post :create, :user => { :name => "root", :pass => "pwd" }
+            assert_response :success
+          end
+
+          it "should support Hash validator without specifying keys" do
+            params = Apipie[UsersController, :create].to_json[:params]
+            params.should include(:name => "facts",
+                                  :full_name => "facts",
+                                  :validator => "Must be Hash",
+                                  :description => "\n<p>Additional optional facts about the user</p>\n",
+                                  :required => false,
+                                  :allow_nil => true,
+                                  :metadata => nil,
+                                  :show => true,
+                                  :expected_type => "hash")
+          end
+
+          it "should allow nil when allow_nil is set to true" do
+            post :create,
+                 :user => {
+                   :name => "root",
+                   :pass => "12345",
+                   :membership => "standard",
+                 },
+                 :facts => nil
+            assert_response :success
+          end
+
+          describe "nested elements"  do
+
+            context "with valid input" do
+              it "should succeed" do
+                put :update,
                     {
-                      :comment => 'comment1'
-                    },
+                      :id => 5,
+                      :user => {
+                        :name => "root",
+                        :pass => "12345"
+                      },
+                      :comments => [
+                        {
+                          :comment => 'comment1'
+                        },
+                        {
+                          :comment => 'comment2'
+                        }
+                      ]
+                    }
+
+                assert_response :success
+              end
+            end
+            context "with bad input" do
+              it "should raise an error" do
+                expect{
+                  put :update,
                     {
-                      :comment => {:bad_input => 5}
+                      :id => 5,
+                      :user => {
+                        :name => "root",
+                        :pass => "12345"
+                      },
+                      :comments => [
+                        {
+                          :comment => 'comment1'
+                        },
+                        {
+                          :comment => {:bad_input => 5}
+                        }
+                      ]
                     }
-                  ]
-                }
-            }.to raise_error(Apipie::ParamInvalid)
+                }.to raise_error(Apipie::ParamInvalid)
+              end
+            end
+            it "should work with empty array" do
+              put :update,
+                  {
+                    :id => 5,
+                    :user => {
+                      :name => "root",
+                      :pass => "12345"
+                    },
+                    :comments => [
+                    ]
+                  }
+
+              assert_response :success
+            end
           end
+
         end
-        it "should work with empty array" do
-          put :update,
-              {
-                :id => 5,
-                :user => {
-                  :name => "root",
-                  :pass => "12345"
-                },
-                :comments => [
-                ]
-              }
-
-          assert_response :success
+      end
+
+      context "using configuration.validate = true" do
+        before :all do
+          Apipie.configuration.validate = true
+          reload_controllers
         end
+
+        it_behaves_like "validates correctly"
       end
 
+      context "using configuration.validate = :implicitly" do
+        before :all do
+          Apipie.configuration.validate = :implicitly
+          reload_controllers
+        end
+
+        it_behaves_like "validates correctly"
+      end
+
+      context "using configuration.validate = :explicitly" do
+        before :all do
+          Apipie.configuration.validate = :explicitly
+          reload_controllers
+        end
+
+        it_behaves_like "validates correctly"
+      end
     end
+
   end
 
   describe "method description" do
@@ -328,6 +383,19 @@ describe UsersController do
       b.full_description.length.should be > 400
     end
 
+    context "Usign routes.rb" do
+      it "should contain basic info about method" do
+        a = Apipie[UsersController, :create_route]
+        a.apis.count.should == 1
+        a.formats.should eq(['json'])
+        api = a.apis.first
+        api.short_description.should eq("Create user")
+        api.path.should eq("/api/users/create_route")
+        api.from_routes.should be_true
+        api.http_method.should eq("POST")
+      end
+    end
+
     context "contain :see option" do
 
       context "the key is valid" do