apipie-rails 0.0.7

data/rel-eng/packages/.readme

@@ -0,0 +1,3 @@
+the rel-eng/packages directory contains metadata files
+named after their packages. Each file has the latest tagged
+version and the project's relative directory.

data/rel-eng/tito.props

@@ -0,0 +1,5 @@
+[globalconfig]
+default_builder = tito.builder.Builder
+default_tagger = tito.tagger.VersionTagger
+changelog_do_not_remove_cherrypick = 0
+changelog_format = %s (%ae)

data/rubygem-apipie-rails.spec

@@ -0,0 +1,72 @@
+%define gem_name apipie-rails
+
+Name: rubygem-%{gem_name}
+Version: 0.0.6
+Release: 1%{?dist}
+Summary: Rails API documentation tool and client generator.
+
+Group: Development/Libraries
+License: MIT
+URL: https://github.com/Pajk/apipie-rails
+Source0: http://rubygems.org/downloads/%{gem_name}-%{version}.gem
+
+%if 0%{?rhel} == 6 || 0%{?fedora} < 17
+%define rubyabi 1.8
+%else
+%define rubyabi 1.9
+%endif
+Requires: ruby(abi) >= %{rubyabi}
+Requires: ruby(rubygems)
+Requires: ruby
+BuildRequires: ruby(abi) >= %{rubyabi}
+BuildRequires: rubygems-devel
+BuildRequires: ruby
+BuildArch: noarch
+Provides: rubygem(%{gem_name}) = %{version}
+
+%description
+This gem adds new methods to Rails controllers that can be used to describe
+resources exposed by API. Informations entered with provided DSL are used
+to generate documentation, client or to validate incoming requests.
+
+%prep
+gem unpack %{SOURCE0}
+%setup -q -D -T -n %{gem_name}-%{version}
+gem spec %{SOURCE0} -l --ruby > %{gem_name}.gemspec
+
+
+%build
+mkdir -p .%{gem_dir}
+
+# Create the gem as gem install only works on a gem file
+gem build %{gem_name}.gemspec
+
+# gem install compiles any C extensions and installs into a directory
+# We set that to be a local directory so that we can move it into the
+# buildroot in %%install
+gem install -V \
+        --local \
+        --install-dir ./%{gem_dir} \
+        --bindir ./%{_bindir} \
+        --force \
+        --rdoc \
+        %{gem_name}-%{version}.gem
+
+%install
+mkdir -p %{buildroot}%{gem_dir}
+cp -a ./%{gem_dir}/* %{buildroot}%{gem_dir}/
+
+%files
+%{gem_dir}/gems/%{gem_name}-%{version}/
+
+
+%doc MIT-LICENSE README.rdoc
+
+%{gem_dir}/cache/%{gem_name}-%{version}.gem
+%{gem_dir}/specifications/%{gem_name}-%{version}.gemspec
+%{gem_docdir}
+
+%changelog
+* Fri Jul 20 2012 Pavel Pokorný <pajkycz@gmail.com> 0.0.6-1
+- new RPM package built with tito
+

data/spec/controllers/apipies_controller_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+require 'fileutils'
+
+describe Apipie::ApipiesController do
+
+  describe "GET index" do
+
+    it "test if route exists" do
+      get :index
+
+      assert_response :success
+    end
+
+  end
+
+  describe "reload_controllers" do
+
+    RSpec::Matchers.define :reload_documentation do
+      match do
+        Apipie.should_receive(:reload_documentation)
+        get :index
+        begin
+          RSpec::Mocks.verify
+        rescue RSpec::Mocks::MockExpectationError
+          false
+        end
+      end
+
+      failure_message_for_should { "the documentation expected to be reloaded but it was not" }
+      failure_message_for_should_not { "the documentation expected not to be reloaded but it was" }
+    end
+
+    before do
+      Apipie.configuration.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
+      if Apipie.configuration.send :instance_variable_defined?, "@reload_controllers"
+        Apipie.configuration.send :remove_instance_variable, "@reload_controllers"
+      end
+    end
+
+    context "it's not specified explicitly" do
+      context "and it's in development environment" do
+        before do
+          Rails.stub(:env => mock(:development? => true))
+        end
+        it { should reload_documentation }
+      end
+
+      context "and it's not development environment" do
+        it { should_not reload_documentation }
+      end
+    end
+
+
+    context "it's explicitly enabled" do
+      before do
+        Apipie.configuration.reload_controllers = true
+      end
+
+      context "and it's in development environment" do
+        before do
+          Rails.stub(:env => mock(:development? => true))
+        end
+        it { should reload_documentation }
+      end
+
+      context "and it's not development environment" do
+        it { should reload_documentation }
+      end
+    end
+
+    context "it's explicitly enabled" do
+      before do
+        Apipie.configuration.reload_controllers = false
+      end
+
+      context "and it's in development environment" do
+        before do
+          Rails.stub(:env => mock(:development? => true))
+        end
+        it { should_not reload_documentation }
+      end
+
+      context "and it's not development environment" do
+        it { should_not reload_documentation }
+      end
+    end
+
+    context "api_controllers_matcher is specified" do
+      before do
+        Apipie.configuration.reload_controllers = true
+        Apipie.configuration.api_controllers_matcher = nil
+      end
+
+      it { should_not reload_documentation }
+    end
+  end
+
+  describe "documentation cache" do
+
+    let(:cache_dir) { File.join(Rails.root, "tmp", "apipie-cache") }
+
+    before do
+      FileUtils.rm_r(cache_dir) if File.exists?(cache_dir)
+      FileUtils.mkdir_p(File.join(cache_dir, "apidoc", "resource"))
+      File.open(File.join(cache_dir, "apidoc.html"), "w") { |f| f << "apidoc.html cache" }
+      File.open(File.join(cache_dir, "apidoc.json"), "w") { |f| f << "apidoc.json cache" }
+      File.open(File.join(cache_dir, "apidoc", "resource.html"), "w") { |f| f << "resource.html cache" }
+      File.open(File.join(cache_dir, "apidoc", "resource", "method.html"), "w") { |f| f << "method.html cache" }
+
+      Apipie.configuration.use_cache = true
+      Apipie.configuration.cache_dir = cache_dir
+    end
+
+    after do
+      FileUtils.rm_r(cache_dir) if File.exists?(cache_dir)
+    end
+
+    it "uses the file in cache dir instead of generating the content on runtime" do
+      get :index
+      response.body.should == "apidoc.html cache"
+      get :index, :format => "html"
+      response.body.should == "apidoc.html cache"
+      get :index, :format => "json"
+      response.body.should == "apidoc.json cache"
+      get :index, :format => "html", :resource => "resource"
+      response.body.should == "resource.html cache"
+      get :index, :format => "html", :resource => "resource", :method => "method"
+      response.body.should == "method.html cache"
+    end
+
+  end
+end

data/spec/controllers/users_controller_spec.rb

@@ -0,0 +1,390 @@
+require 'spec_helper'
+
+def compare_hashes(h1, h2)
+  h1.each do |key, val|
+    if val.is_a? Hash
+      compare_hashes val, h2[key]
+    elsif val.is_a? Array
+      val.each_with_index do |v, i|
+        compare_hashes val[i], h2[key][i]
+      end
+    else
+      val.should eq(h2[key])
+    end
+  end
+end
+
+describe UsersController do
+
+  describe "resource description" do
+    subject { a = Apipie.get_resource_description(UsersController) }
+
+    it "should contain all resource methods" do
+      methods = subject._methods
+      methods.count.should == 5
+      methods.should include("users#show")
+      methods.should include("users#create")
+      methods.should include("users#index")
+      methods.should include("users#two_urls")
+    end
+
+    it "should contain info about resource" do
+      subject._short_description.should eq('Site members')
+      subject._id.should eq('users')
+      subject._path.should eq('/users')
+      subject._version.should eq('1.0 - 3.4.2012')
+      subject._name.should eq('Members')
+    end
+
+    it "should contain params defined on resource level" do
+      subject._params_ordered.count.should == 2
+      p = subject._params_ordered.first
+      p.should_not be(nil)
+      p.name.should eq(:id)
+      p.desc.should eq("\n<p>User ID</p>\n")
+      p.required.should eq(false)
+      p.validator.class.should eq(Apipie::Validator::IntegerValidator)
+
+      p = subject._params_ordered.second
+      p.should_not be(nil)
+      p.name.should eq(:resource_param)
+      p.desc.should eq("\n<p>Param description for all methods</p>\n")
+      p.required.should eq(false)
+      p.validator.class.should eq(Apipie::Validator::HashValidator)
+    end
+  end
+
+  describe "validators" do
+
+    context "validations are disabled" do
+      before { Apipie.configuration.validate = false }
+
+      it "should reply to valid request" do
+        get :show, :id => '5', :session => "secret_hash"
+        assert_response :success
+      end
+
+      it "should pass if required parameter is missing" do
+        lambda { get :show, :id => 5 }.should_not raise_error
+      end
+
+    end
+
+
+    context "validations are enabled" do
+      before { Apipie.configuration.validate = true }
+
+      it "should reply to valid request" do
+        get :show, :id => '5', :session => "secret_hash"
+        assert_response :success
+      end
+
+      it "should fail if required parameter is missing" do
+        lambda { get :show, :id => 5 }.should raise_error(ArgumentError, / session /)
+      end
+
+      it "should work with Type validator" do
+        lambda {
+          get :show,
+              :id => "not a number",
+              :session => "secret_hash"
+        }.should raise_error(ArgumentError, / id /)
+      end
+
+      it "should work with Regexp validator" do
+        get :show,
+            :id => 5,
+            :session => "secret_hash",
+            :regexp_param => "24 years"
+        assert_response :success
+
+        lambda {
+          get :show,
+              :id => 5,
+              :session => "secret_hash",
+              :regexp_param => "ten years"
+        }.should raise_error(ArgumentError, / regexp_param /)
+      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
+
+        lambda {
+          get :show,
+              :id => 5,
+              :session => "secret_hash",
+              :array_param => "blabla"
+        }.should raise_error(ArgumentError, / array_param /)
+
+        lambda {
+          get :show,
+              :id => 5,
+              :session => "secret_hash",
+              :array_param => 3
+        }.should raise_error(ArgumentError, / array_param /)
+      end
+
+      it "should work with Proc validator" do
+        lambda {
+          get :show,
+              :id => 5,
+              :session => "secret_hash",
+              :proc_param => "asdgsag"
+        }.should raise_error(ArgumentError, / proc_param /)
+
+        get :show,
+            :id => 5,
+            :session => "secret_hash",
+            :proc_param => "param value"
+        assert_response :success
+      end
+
+      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.hash_params_ordered
+        hash_params.count.should == 3
+        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(ArgumentError, / membership /)
+
+        lambda {
+          post :create, :user => { :name => "root" }
+        }.should raise_error(ArgumentError, / pass /)
+
+        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 => "Parameter has to be Hash.",
+                              :description => "\n<p>Additional optional facts about the user</p>\n",
+                              :required => false,
+                              :allow_nil => 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
+
+    end
+  end
+
+  describe "method description" do
+
+    it "should contain basic info about method" do
+      a = Apipie[UsersController, :create]
+      a.apis.count.should == 1
+      api = a.apis.first
+      api.short_description.should eq("Create user")
+      api.api_url.should eq("/api/users")
+      api.http_method.should eq("POST")
+
+      b = Apipie.get_method_description(UsersController, :show)
+      b.should eq(Apipie[UsersController, :show])
+      b.method.should eq(:show)
+      b.resource._id.should eq('users')
+
+      b.apis.count.should == 1
+      api = b.apis.first
+      api.short_description.should eq("Show user profile")
+      api.api_url.should eq("#{Apipie.configuration.api_base_url}/users/:id")
+      api.http_method.should eq("GET")
+      b.full_description.length.should be > 400
+    end
+
+    context "contain :see option" do
+
+      context "the key is valid" do 
+        it "should contain reference to another method" do
+          api = Apipie[UsersController, :see_another]
+          api.see.should eq('users#create')
+          Apipie['users#see_another'].should eq(Apipie[UsersController, :see_another])
+          api.see_url.should eq(Apipie[UsersController, :create].doc_url)
+        end
+      end
+
+      context "the key is not valid" do
+        it "should raise exception" do
+          api = Apipie[UsersController, :see_another]
+          api.instance_variable_set :@see, 'doesnot#exist'
+          lambda {
+            api.see_url
+          }.should raise_error(ArgumentError, /does not exist/)
+          api.instance_variable_set :@see, nil
+        end
+      end
+    end
+
+    it "should contain possible errors description" do
+      a = Apipie.get_method_description(UsersController, :show)
+
+      a.errors[0].code.should eq(401)
+      a.errors[0].description.should eq("Unauthorized")
+      a.errors[1].code.should eq(404)
+      a.errors[1].description.should eq("Not Found")
+    end
+
+    it "should contain all params description" do
+      a = Apipie.get_method_description(UsersController, :show)
+      a.params.count.should == 8
+      a.instance_variable_get('@params_ordered').count.should == 6
+    end
+
+    it "should contain all api method description" do
+      method_description = Apipie[UsersController, :two_urls]
+      method_description.class.should be(Apipie::MethodDescription)
+      method_description.apis.count.should == 2
+      a1, a2 = method_description.apis
+
+      a1.short_description.should eq('Get company users')
+      a1.api_url.should eq('/api/company_users')
+      a1.http_method.should eq('GET')
+
+      a2.short_description.should eq('Get users working in given company')
+      a2.api_url.should eq('/api/company/:id/users')
+      a2.http_method.should eq('GET')
+    end
+
+    it "should be described by valid json" do
+      json = Apipie[UsersController, :two_urls].to_json
+      expected_hash = {
+        :errors => [],
+        :examples => [],
+        :doc_url => "#{Apipie.configuration.doc_base_url}/users/two_urls",
+        :full_description => '',
+        :params => [{:full_name=>"oauth",
+                     :required=>false,
+                     :allow_nil => false,
+                     :validator=>"Parameter has to be String.",
+                     :description=>"\n<p>Authorization</p>\n",
+                     :name=>"oauth",
+                     :expected_type=>"string"},
+                    {:validator=>"Has to be hash.",
+                     :description=>"\n<p>Param description for all methods</p>\n",
+                     :expected_type=>"hash",
+                     :allow_nil=>false,
+                     :name=>"resource_param",
+                     :required=>false,
+                     :full_name=>"resource_param",
+                     :params=>
+                      [{:required=>true,
+                        :allow_nil => false,
+                        :validator=>"Parameter has to be String.",
+                        :description=>"\n<p>Username for login</p>\n",
+                        :name=>"ausername", :full_name=>"resource_param[ausername]",
+                        :expected_type=>"string"},
+                       {:required=>true,
+                        :allow_nil => false,
+                        :validator=>"Parameter has to be String.",
+                        :description=>"\n<p>Password for login</p>\n",
+                        :name=>"apassword", :full_name=>"resource_param[apassword]",
+                        :expected_type=>"string"}
+                      ]
+                    },
+                    {:required=>false, :validator=>"Parameter has to be Integer.",
+                     :allow_nil => false,
+                     :description=>"\n<p>Company ID</p>\n",
+                     :name=>"id", :full_name=>"id",
+                     :expected_type=>"numeric"},
+       ],
+        :name => :two_urls,
+        :apis => [
+          {
+            :http_method => 'GET',
+            :short_description => 'Get company users',
+            :api_url => "#{Apipie.configuration.api_base_url}/company_users"
+          },{
+            :http_method => 'GET',
+            :short_description => 'Get users working in given company',
+            :api_url =>"#{Apipie.configuration.api_base_url}/company/:id/users"
+          }
+        ]
+      }
+
+      compare_hashes json, expected_hash
+    end
+
+  end
+
+  describe "examples" do
+
+    it "should be able to load examples from yml file" do
+      Apipie.get_method_description(UsersController, :show).examples.should == [<<EOS1, <<EOS2].map(&:chomp)
+GET /users/14?verbose=true
+200
+{
+  "name": "Test User"
+}
+EOS1
+GET /users/15
+404
+EOS2
+    end
+  end
+
+  describe "param description" do
+
+    it "should contain all specified information" do
+      a = Apipie.get_method_description(UsersController, :show)
+
+      param = a.params[:session]
+      param.required.should eq(true)
+      param.desc.should eq("\n<p>user is logged in</p>\n")
+      param.validator.class.should be(Apipie::Validator::TypeValidator)
+      param.validator.instance_variable_get("@type").should eq(String)
+
+      param = a.params[:id]
+      param.required.should eq(true)
+      param.desc.should eq("\n<p>user id</p>\n")
+      param.validator.class.should be(Apipie::Validator::IntegerValidator)
+      param.validator.instance_variable_get("@type").should eq(Integer)
+
+      param = a.params[:regexp_param]
+      param.desc.should eq("\n<p>regexp param</p>\n")
+      param.required.should eq(false)
+      param.validator.class.should be(Apipie::Validator::RegexpValidator)
+      param.validator.instance_variable_get("@regexp").should
+        eq(/^[0-9]* years/)
+
+      param = a.params[:array_param]
+      param.desc.should eq("\n<p>array validator</p>\n")
+      param.validator.class.should be(Apipie::Validator::ArrayValidator)
+      param.validator.instance_variable_get("@array").should
+        eq([100, "one", "two", 1, 2])
+
+      param = a.params[:proc_param]
+      param.desc.should eq("\n<p>proc validator</p>\n")
+      param.validator.class.should be(Apipie::Validator::ProcValidator)
+    end
+
+  end
+
+end