apipie-rails 0.0.24 → 0.1.0

data/lib/apipie/method_description.rb

@@ -15,7 +15,7 @@ module Apipie
 
     end
 
-    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats
+    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :metadata
 
     def initialize(method, resource, dsl_data)
       @method = method.to_s
@@ -30,7 +30,7 @@ module Apipie
       @full_description = Apipie.markup_to_html(desc)
 
       @errors = dsl_data[:errors].map do |args|
-        Apipie::ErrorDescription.new(args)
+        Apipie::ErrorDescription.from_dsl_data(args)
       end
 
       @see = dsl_data[:see].map do |args|
@@ -41,6 +41,8 @@ module Apipie
       @examples = dsl_data[:examples]
       @examples += load_recorded_examples
 
+      @metadata = dsl_data[:meta]
+
       @params_ordered = dsl_data[:params].map do |args|
         Apipie::ParamDescription.from_dsl_data(self, args)
       end
@@ -76,7 +78,7 @@ module Apipie
       @merged_errors = []
       if @resource
         resource_errors = @resource._errors_args.map do |args|
-          Apipie::ErrorDescription.new(args)
+          Apipie::ErrorDescription.from_dsl_data(args)
         end
 
         # exclude overwritten parent errors
@@ -101,7 +103,7 @@ module Apipie
     end
 
     def create_api_url(api)
-      path = "#{Apipie.api_base_url(@resource._version)}#{api.path}"
+      path = "#{@resource._api_base_url}#{api.path}"
       path = path[0..-2] if path[-1..-1] == '/'
       return path
     end
@@ -134,6 +136,7 @@ module Apipie
         :errors => errors.map(&:to_json),
         :params => params_ordered.map(&:to_json).flatten,
         :examples => @examples,
+        :metadata => @metadata,
         :see => see.map(&:to_json)
       }
     end

data/lib/apipie/middleware/checksum_in_headers.rb

@@ -0,0 +1,35 @@
+# Middleware for rails app that adds checksum of JSON in the response headers
+# which can help client to realize when JSON has changed
+#
+# Add the following to your application.rb
+#   require 'apipie/middleware/checksum_in_headers'
+#   # Add JSON checksum in headers for smarter caching
+#   config.middleware.use "Apipie::Middleware::ChecksumInHeaders"
+#
+# And in your apipie initializer allow checksum calculation
+#   Apipie.configuration.update_checksum = true
+# and reload documentation
+#   Apipie.reload_documentation
+#
+# By default the header is added to requests on /api and /apipie only
+# It can be changed with
+#   Apipie.configuration.checksum_path = ['/prefix/api']
+# If set to nil the header is added always
+
+module Apipie
+  module Middleware
+    class ChecksumInHeaders
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        if !Apipie.configuration.checksum_path || env['PATH_INFO'].start_with?(*Apipie.configuration.checksum_path)
+          headers.merge!( 'Apipie-Checksum' => Apipie.checksum )
+        end
+        return [status, headers, body]
+      end
+    end
+  end
+end

data/lib/apipie/param_description.rb

@@ -8,8 +8,7 @@ module Apipie
   # validator - Validator::BaseValidator subclass
   class ParamDescription
 
-    attr_reader :method_description, :name, :desc, :allow_nil, :validator, :options
-
+    attr_reader :method_description, :name, :desc, :allow_nil, :validator, :options, :metadata, :show, :as
     attr_accessor :parent, :required
 
     def self.from_dsl_data(method_description, args)
@@ -39,14 +38,23 @@ module Apipie
 
       @method_description = method_description
       @name = concern_subst(name)
+      @as = options[:as] || @name
       @desc = concern_subst(Apipie.markup_to_html(@options[:desc] || ''))
       @parent = @options[:parent]
+      @metadata = @options[:meta]
+
       @required = if @options.has_key? :required
         @options[:required]
       else
         Apipie.configuration.required_by_default?
       end
 
+      @show = if @options.has_key? :show
+        @options[:show]
+      else
+        true
+      end
+
       @allow_nil = @options[:allow_nil] || false
 
       action_awareness
@@ -59,15 +67,24 @@ module Apipie
 
     def validate(value)
       return true if @allow_nil && value.nil?
-      unless @validator.valid?(value)
+      if (!@allow_nil && value.nil?) || !@validator.valid?(value)
         error = @validator.error
         error = ParamError.new(error) unless error.is_a? StandardError
         raise error
       end
     end
 
+    def process_value(value)
+      if @validator.respond_to?(:process_value)
+        @validator.process_value(value)
+      else
+        value
+      end
+    end
+
     def full_name
-      name_parts = parents_and_self.map(&:name)
+      name_parts = parents_and_self.map{|p| p.name if p.show}.compact
+      return name.to_s if name_parts.blank?
       return ([name_parts.first] + name_parts[1..-1].map { |n| "[#{n}]" }).join("")
     end
 
@@ -92,6 +109,8 @@ module Apipie
           :allow_nil => allow_nil,
           :validator => validator.to_s,
           :expected_type => validator.expected_type,
+          :metadata => metadata,
+          :show => show,
           :params => validator.hash_params_ordered.map(&:to_json)
         }
       else
@@ -102,6 +121,8 @@ module Apipie
           :required => required,
           :allow_nil => allow_nil,
           :validator => validator.to_s,
+          :metadata => metadata,
+          :show => show,
           :expected_type => validator.expected_type
         }
       end

data/lib/apipie/resource_description.rb

@@ -12,7 +12,7 @@ module Apipie
   class ResourceDescription
 
     attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
-      :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent
+      :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent, :_metadata
 
     def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
 
@@ -37,19 +37,22 @@ module Apipie
       @_formats = dsl_data[:formats]
       @_errors_args = dsl_data[:errors]
       @_params_args = dsl_data[:params]
+      @_metadata = dsl_data[:meta]
+      @_api_base_url = dsl_data[:api_base_url]
 
       if dsl_data[:app_info]
         Apipie.configuration.app_info[_version] = dsl_data[:app_info]
       end
-      if dsl_data[:api_base_url]
-        Apipie.configuration.api_base_url[_version] = dsl_data[:api_base_url]
-      end
     end
 
     def _version
       @_version || @_parent.try(:_version) || Apipie.configuration.default_version
     end
 
+    def _api_base_url
+      @_api_base_url || @_parent.try(:_api_base_url) || Apipie.api_base_url(_version)
+    end
+
     def add_method_description(method_description)
       Apipie.debug "@resource_descriptions[#{self._version}][#{self._name}]._methods[#{method_description.method}] = #{method_description}"
       @_methods[method_description.method.to_sym] = method_description
@@ -94,6 +97,7 @@ module Apipie
         :full_description => @_full_description,
         :version => _version,
         :formats => @_formats,
+        :metadata => @_metadata,
         :methods => methods
       }
     end

data/lib/apipie/routing.rb

@@ -3,6 +3,7 @@ module Apipie
     module MapperExtensions
       def apipie
         namespace "apipie", :path => Apipie.configuration.doc_base_url do
+          get 'apipie_checksum', to: "apipies#apipie_checksum", :format => "json"
           constraints(:version => /[^\/]+/) do
             get("(:version)/(:resource)/(:method)" => "apipies#index", :as => :apipie)
           end

data/lib/apipie/validator.rb

@@ -150,6 +150,28 @@ module Apipie
       end
     end
 
+    class ArrayClassValidator < BaseValidator
+
+      def initialize(param_description, argument)
+        super(param_description)
+        @array = argument
+      end
+
+      def validate(value)
+        @array.include?(value.class)
+      end
+
+      def self.build(param_description, argument, options, block)
+        if argument.is_a?(Array) && argument.first.class == Class && !block.is_a?(Proc)
+          self.new(param_description, argument)
+        end
+      end
+
+      def description
+        "Must be one of: #{@array.join(', ')}."
+      end
+    end
+
     class ProcValidator < BaseValidator
 
       def initialize(param_description, argument)
@@ -205,6 +227,7 @@ module Apipie
       end
 
       def validate(value)
+        return false if !value.is_a? Hash
         if @hash_params
           @hash_params.each do |k, p|
             if Apipie.configuration.validate_presence?
@@ -218,6 +241,16 @@ module Apipie
         return true
       end
 
+      def process_value(value)
+        if @hash_params && value
+          return @hash_params.each_with_object({}) do |(key, param), api_params|
+            if value.has_key?(key)
+              api_params[param.as] = param.process_value(value[key])
+            end
+          end
+        end
+      end
+
       def description
         "Must be a Hash"
       end
@@ -250,7 +283,7 @@ module Apipie
 
 
     # special type of validator: we say that it's not specified
-    class UndefValidator < Apipie::Validator::BaseValidator
+    class UndefValidator < BaseValidator
 
       def validate(value)
         true
@@ -267,7 +300,7 @@ module Apipie
       end
     end
 
-    class NumberValidator < Apipie::Validator::BaseValidator
+    class NumberValidator < BaseValidator
 
       def validate(value)
         self.class.validate(value)
@@ -288,7 +321,7 @@ module Apipie
       end
     end
 
-    class BooleanValidator < Apipie::Validator::BaseValidator
+    class BooleanValidator < BaseValidator
 
       def validate(value)
         %w[true false].include?(value.to_s)
@@ -305,6 +338,41 @@ module Apipie
       end
     end
 
+    class NestedValidator < BaseValidator
+
+      def initialize(param_description, argument, param_group)
+        super(param_description)
+        @validator = Apipie::Validator:: HashValidator.new(param_description, argument, param_group)
+        @type = argument
+      end
+
+      def validate(value)
+        value ||= [] # Rails convert empty array to nil
+        return false if value.class != Array
+        value.each do |child|
+          return false unless @validator.validate(child)
+        end
+        true
+      end
+
+      def process_value(value)
+        value ||= [] # Rails convert empty array to nil
+        @values = []
+        value.each do |child|
+          @values << @validator.process_value(child)
+        end
+        @values
+      end
+
+      def self.build(param_description, argument, options, block)
+        self.new(param_description, block, options[:param_group]) if block.is_a?(Proc) && block.arity == 0 && argument == Array
+      end
+
+      def description
+        "Must be an Array of nested elements"
+      end
+    end
+
   end
 end
 

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = '0.0.24'
+  VERSION = '0.1.0'
 end

data/lib/tasks/apipie.rake

@@ -35,6 +35,16 @@ namespace :apipie do
     end
   end
 
+  desc "Generate static documentation json"
+  task :static_json, [:version] => :environment do |t, args|
+    with_loaded_documentation do
+      args.with_defaults(:version => Apipie.configuration.default_version)
+      out = ENV["OUT"] || File.join(::Rails.root, 'doc', 'apidoc')
+      doc = Apipie.to_json(args[:version])
+      generate_json_page(out, doc)
+    end
+  end
+
   desc "Generate cache to avoid production dependencies on markup languages"
   task :cache => :environment do
     with_loaded_documentation do
@@ -60,11 +70,15 @@ namespace :apipie do
 
   # Attempt to use the Rails application views, otherwise default to built in views
   def renderer
-    if File.directory?("#{Rails.root}/app/views/apipie/apipies")
-      ActionView::Base.new("#{Rails.root}/app/views/apipie/apipies")
-    else
-      ActionView::Base.new(File.expand_path("../../../app/views/apipie/apipies", __FILE__))
-    end
+    return @apipie_renderer if @apipie_renderer
+    base_path = if File.directory?("#{Rails.root}/app/views/apipie/apipies")
+                  "#{Rails.root}/app/views/apipie/apipies"
+                else
+                  File.expand_path("../../../app/views/apipie/apipies", __FILE__)
+                end
+    @apipie_renderer = ActionView::Base.new(base_path)
+    @apipie_renderer.singleton_class.send(:include, ApipieHelper)
+    return @apipie_renderer
   end
 
   def render_page(file_name, template, variables, layout = 'apipie')
@@ -79,6 +93,13 @@ namespace :apipie do
     end
   end
 
+  def generate_json_page(file_base, doc)
+    FileUtils.mkdir_p(file_base) unless File.exists?(file_base)
+
+    filename = 'schema_apipie.json'
+    File.open("#{file_base}/#{filename}", 'w') { |file| file.write(JSON.pretty_generate(doc)) }
+  end
+
   def generate_one_page(file_base, doc)
     FileUtils.mkdir_p(File.dirname(file_base)) unless File.exists?(File.dirname(file_base))
 

data/spec/controllers/apipies_controller_spec.rb

@@ -120,6 +120,7 @@ describe Apipie::ApipiesController do
       File.open(File.join(cache_dir, "apidoc", "v1", "resource", "method.html"), "w") { |f| f << "method.html cache" }
 
       Apipie.configuration.use_cache = true
+      @orig_cache_dir = Apipie.configuration.cache_dir
       Apipie.configuration.cache_dir = cache_dir
       @orig_version = Apipie.configuration.default_version
       Apipie.configuration.default_version = 'v1'
@@ -128,6 +129,7 @@ describe Apipie::ApipiesController do
     after do
       Apipie.configuration.use_cache = false
       Apipie.configuration.default_version = @orig_version
+      Apipie.configuration.cache_dir = @orig_cache_dir
       # FileUtils.rm_r(cache_dir) if File.exists?(cache_dir)
     end
 

data/spec/controllers/concerns_controller_spec.rb

@@ -13,7 +13,7 @@ describe ConcernsController do
   end
 
   it "should pass if required parameter is missing" do
-    lambda { get :show, :id => 5 }.should_not raise_error
+    lambda { get :show, :id => '5' }.should_not raise_error
   end
 
   it "peserved the order of methods being defined in file" do

data/spec/controllers/users_controller_spec.rb

@@ -110,6 +110,13 @@ describe UsersController do
         assert_response :success
       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
+
       it "should fail if required parameter is missing" do
         lambda { get :show, :id => 5 }.should raise_error(Apipie::ParamMissing, /\bsession\b/)
       end
@@ -142,7 +149,7 @@ describe UsersController do
         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
+        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
@@ -199,6 +206,10 @@ describe UsersController do
           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
@@ -211,6 +222,8 @@ describe UsersController do
                               :description => "\n<p>Additional optional facts about the user</p>\n",
                               :required => false,
                               :allow_nil => true,
+                              :metadata => nil,
+                              :show => true,
                               :expected_type => "hash")
       end
 
@@ -225,6 +238,67 @@ describe UsersController do
         assert_response :success
       end
 
+      describe "nested elements"  do
+
+        context "with valid input" do
+          it "should succeed" do
+            put :update,
+                {
+                  :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,
+                {
+                  :id => 5,
+                  :user => {
+                    :name => "root",
+                    :pass => "12345"
+                  },
+                  :comments => [
+                    {
+                      :comment => 'comment1'
+                    },
+                    {
+                      :comment => {bad_input: 5}
+                    }
+                  ]
+                }
+            }.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
   end
 
@@ -297,8 +371,8 @@ describe UsersController do
 
     it "should contain all params description" do
       a = Apipie.get_method_description(UsersController, :show)
-      a.params.count.should == 9
-      a.instance_variable_get('@params_ordered').count.should == 7
+      a.params.count.should == 11
+      a.instance_variable_get('@params_ordered').count.should == 9
     end
 
     it "should contain all api method description" do
@@ -319,7 +393,7 @@ describe UsersController do
     it "should be described by valid json" do
       json = Apipie[UsersController, :two_urls].to_json
       expected_hash = {
-        :errors => [{:code=>404, :description=>"Missing"},
+        :errors => [{:code=>404, :description=>"Missing", :metadata => {:some => "metadata"}},
                     {:code=>500, :description=>"Server crashed for some <%= reason %>"}],
         :examples => [],
         :doc_url => "#{Apipie.configuration.doc_base_url}/development/users/two_urls",
@@ -331,33 +405,48 @@ describe UsersController do
                      :validator=>"Must be String",
                      :description=>"\n<p>Authorization</p>\n",
                      :name=>"oauth",
+                     :show=>true,
                      :expected_type=>"string"},
                     {:validator=>"Must be a Hash",
-                     :description=>"\n<p>Param description for all methods</p>\n",
+                     :description=>"\n<p>Deprecated parameter not documented</p>\n",
                      :expected_type=>"hash",
                      :allow_nil=>false,
-                     :name=>"resource_param",
+                     :name=>"legacy_param",
                      :required=>false,
-                     :full_name=>"resource_param",
+                     :full_name=>"legacy_param",
+                     :show=>false,
                      :params=>
-                      [{:required=>true,
-                        :allow_nil => false,
-                        :validator=>"Must 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=>"Must be String",
-                        :description=>"\n<p>Password for login</p>\n",
-                        :name=>"apassword", :full_name=>"resource_param[apassword]",
-                        :expected_type=>"string"}
+                      [{:validator=>"Must be a 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",
+                        :show=>true,
+                        :params=>
+                        [{:required=>true,
+                          :allow_nil => false,
+                          :validator=>"Must be String",
+                          :description=>"\n<p>Username for login</p>\n",
+                          :name=>"ausername", :full_name=>"resource_param[ausername]",
+                          :show=>true,
+                          :expected_type=>"string"},
+                         {:required=>true,
+                          :allow_nil => false,
+                          :validator=>"Must be String",
+                          :description=>"\n<p>Password for login</p>\n",
+                          :name=>"apassword", :full_name=>"resource_param[apassword]",
+                          :show=>true,
+                          :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",
+                     :show=>true,
                      :expected_type=>"numeric"},
        ],
         :name => 'two_urls',
@@ -476,4 +565,26 @@ EOS2
       end
     end
   end
+
+  describe "Parameter processing / extraction" do
+    before do
+      Apipie.configuration.process_params = true
+    end
+
+    it "process correctly the parameters" do
+      post :create, {:user => {:name => 'dummy', :pass => 'dummy', :membership => 'standard'}, :facts => nil}
+
+      expect(assigns(:api_params).with_indifferent_access).to eq({:user => {:name=>"dummy", :pass=>"dummy", :membership=>"standard"}, :facts => nil}.with_indifferent_access)
+    end
+
+    it "ignore not described parameters" do
+      post :create, {:user => {:name => 'dummy', :pass => 'dummy', :membership => 'standard', :id => 0}}
+
+      expect(assigns(:api_params).with_indifferent_access).to eq({:user => {:name=>"dummy", :pass=>"dummy", :membership=>"standard"}}.with_indifferent_access)
+    end
+
+    after do
+      Apipie.configuration.process_params = false
+    end
+  end
 end