apipie-rails 0.0.17 → 0.0.18

data/lib/apipie/method_description.rb

@@ -17,26 +17,33 @@ module Apipie
 
     attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats
 
-    def initialize(method, resource, app)
+    def initialize(method, resource, dsl_data)
       @method = method.to_s
       @resource = resource
 
-      @apis = app.last_dsl_data[:api_args]
-      @see = app.last_dsl_data[:see]
-      @formats = app.last_dsl_data[:formats]
+      @apis = dsl_data[:api_args].map do |method, path, desc|
+        MethodDescription::Api.new(method, path, desc)
+      end
 
-      desc = app.last_dsl_data[:description] || ''
+      desc = dsl_data[:description] || ''
       @full_description = Apipie.markup_to_html(desc)
-      @errors = app.last_dsl_data[:errors]
-      @params_ordered = app.last_dsl_data[:params]
-      @examples = app.last_dsl_data[:examples]
 
+      @errors = dsl_data[:errors].map do |args|
+        Apipie::ErrorDescription.new(args)
+      end
+
+      @see = dsl_data[:see].map do |args|
+        Apipie::SeeDescription.new(args)
+      end
+
+      @formats = dsl_data[:formats]
+      @examples = dsl_data[:examples]
       @examples += load_recorded_examples
 
-      parent = @resource.controller.superclass
-      if parent != ActionController::Base
-        @parent_resource = parent.controller_name
+      @params_ordered = dsl_data[:params].map do |args|
+        Apipie::ParamDescription.from_dsl_data(self, args)
       end
+      @params_ordered = ParamDescription.unify(@params_ordered)
     end
 
     def id
@@ -49,15 +56,14 @@ module Apipie
 
     def params_ordered
       all_params = []
-      # get params from parent resource description
-      if @parent_resource
-        parent = Apipie.get_resource_description(@parent_resource)
-        merge_params(all_params, parent._params_ordered) if parent
-      end
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
 
-      # get params from actual resource description
-      if @resource
-        merge_params(all_params, resource._params_ordered)
+      # get params from parent resource description
+      [parent, @resource].compact.each do |resource|
+        resource_params = resource._params_args.map do |args|
+          Apipie::ParamDescription.from_dsl_data(self, args)
+        end
+        merge_params(all_params, resource_params)
       end
 
       merge_params(all_params, @params_ordered)
@@ -68,8 +74,12 @@ module Apipie
       return @merged_errors if @merged_errors
       @merged_errors = []
       if @resource
+        resource_errors = @resource._errors_args.map do |args|
+          Apipie::ErrorDescription.new(args)
+        end
+
         # exclude overwritten parent errors
-        @merged_errors = @resource._errors_ordered.find_all do |err|
+        @merged_errors = resource_errors.find_all do |err|
           !@errors.any? { |e| e.code == err.code }
         end
       end

data/lib/apipie/param_description.rb

@@ -8,14 +8,24 @@ module Apipie
   # validator - Validator::BaseValidator subclass
   class ParamDescription
 
-    attr_reader :name, :desc, :required, :allow_nil, :validator
+    attr_reader :method_description, :name, :desc, :allow_nil, :validator, :options
 
-    attr_accessor :parent
+    attr_accessor :parent, :required
 
-    def initialize(name, validator, desc_or_options = nil, options = {}, &block)
+    def self.from_dsl_data(method_description, args)
+      param_name, validator, desc_or_options, options, block = args
+      Apipie::ParamDescription.new(method_description,
+                                   param_name,
+                                   validator,
+                                   desc_or_options,
+                                   options,
+                                   &block)
+    end
+
+    def initialize(method_description, name, validator, desc_or_options = nil, options = {}, &block)
 
-      if desc_or_options.is_a?(Hash) && options.empty?
-        options = desc_or_options
+      if desc_or_options.is_a?(Hash)
+        options = options.merge(desc_or_options)
       elsif desc_or_options.is_a?(String)
         options[:desc] = desc_or_options
       elsif !desc_or_options.nil?
@@ -24,19 +34,27 @@ module Apipie
 
       options.symbolize_keys!
 
+      # we save options to know what was passed in DSL
+      @options = options
+
+      @method_description = method_description
       @name = name
-      @desc = Apipie.markup_to_html(options[:desc] || '')
-      @required = if options.has_key? :required
-        options[:required]
+      @desc = Apipie.markup_to_html(@options[:desc] || '')
+      @parent = @options[:parent]
+      @required = if @options.has_key? :required
+        @options[:required]
       else
         Apipie.configuration.required_by_default?
       end
-      @allow_nil = options[:allow_nil] || false
+
+      @allow_nil = @options[:allow_nil] || false
+
+      action_awareness
 
       @validator = nil
       unless validator.nil?
         @validator =
-          Validator::BaseValidator.find(self, validator, options, block)
+          Validator::BaseValidator.find(self, validator, @options, block)
         raise "Validator not found." unless validator
       end
     end
@@ -91,6 +109,76 @@ module Apipie
       end
     end
 
+    def merge_with(other_param_desc)
+      if self.validator && other_param_desc.validator
+        self.validator.merge_with(other_param_desc.validator)
+      else
+        self.validator ||= other_param_desc.validator
+      end
+      self
+    end
+
+    # merge param descripsiont. Allows defining hash params on more places
+    # (e.g. in param_groups). For example:
+    #
+    #     def_param_group :user do
+    #       param :user, Hash do
+    #         param :name, String
+    #       end
+    #     end
+    #
+    #     param_group :user
+    #     param :user, Hash do
+    #       param :password, String
+    #     end
+    def self.unify(params)
+      ordering = params.map(&:name)
+      params.group_by(&:name).map do |name, param_descs|
+        param_descs.reduce(&:merge_with)
+      end.sort_by { |param| ordering.index(param.name) }
+    end
+
+    # action awareness is being inherited from ancestors (in terms of
+    # nested params)
+    def action_aware?
+      if @options.has_key?(:action_aware)
+        return @options[:action_aware]
+      elsif @parent
+        @parent.action_aware?
+      else
+        false
+      end
+    end
+
+    def as_action
+      if @options[:param_group] && @options[:param_group][:options] &&
+          @options[:param_group][:options][:as]
+        @options[:param_group][:options][:as].to_s
+      elsif @parent
+        @parent.as_action
+      else
+        @method_description.method
+      end
+    end
+
+    # makes modification that are based on the action that the param
+    # is defined for. Typical for required and allow_nil variations in
+    # crate/update actions.
+    def action_awareness
+      if action_aware?
+        if !@options.has_key?(:allow_nil)
+          if @required
+            @allow_nil = false
+          else
+            @allow_nil = true
+          end
+        end
+        if as_action != "create"
+          @required = false
+        end
+      end
+    end
+
   end
 
 end

data/lib/apipie/railtie.rb

@@ -2,7 +2,10 @@ module Apipie
   class Railtie < Rails::Railtie
     initializer 'apipie.controller_additions' do
       ActiveSupport.on_load :action_controller do
-        extend Apipie::DSL
+        extend Apipie::DSL::Base
+        extend Apipie::DSL::Common
+        extend Apipie::DSL::Action
+        extend Apipie::DSL::Param
       end
     end
   end

data/lib/apipie/resource_description.rb

@@ -12,13 +12,13 @@ module Apipie
   class ResourceDescription
 
     attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
-      :_path, :_name, :_params_ordered, :_errors_ordered, :_formats, :_parent
+      :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent
 
     def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
 
       @_methods = ActiveSupport::OrderedHash.new
-      @_params_ordered = []
-      @_errors_ordered = []
+      @_params_args = []
+      @_errors_args = []
 
       @controller = controller
       @_id = resource_name
@@ -35,8 +35,9 @@ module Apipie
       @_short_description = dsl_data[:short_description]
       @_path = dsl_data[:path] || ""
       @_formats = dsl_data[:formats]
-      @_errors_ordered = dsl_data[:errors]
-      @_params_ordered = dsl_data[:params]
+      @_errors_args = dsl_data[:errors]
+      @_params_args = dsl_data[:params]
+
       if dsl_data[:app_info]
         Apipie.configuration.app_info[_version] = dsl_data[:app_info]
       end

data/lib/apipie/validator.rb

@@ -66,6 +66,10 @@ module Apipie
         'string'
       end
 
+      def merge_with(other_validator)
+        raise NotImplementedError, "Dont know how to merge #{self.inspect} with #{other_validator.inspect}"
+      end
+
     end
 
     # validate arguments type
@@ -169,20 +173,33 @@ module Apipie
     end
 
     class HashValidator < BaseValidator
-
-      attr_reader :hash_params_ordered
+      include Apipie::DSL::Base
+      include Apipie::DSL::Param
 
       def self.build(param_description, argument, options, block)
-        self.new(param_description, block) if block.is_a?(Proc) && block.arity <= 0 && argument == Hash
+        self.new(param_description, block, options[:param_group]) if block.is_a?(Proc) && block.arity <= 0 && argument == Hash
       end
 
-      def initialize(param_description, argument)
+      def initialize(param_description, argument, param_group)
         super(param_description)
         @proc = argument
-        @hash_params_ordered = []
-        @hash_params = {}
-
+        @param_group = param_group
         self.instance_exec(&@proc)
+        # specifying action_aware on Hash influences the child params,
+        # not the hash param itself: assuming it's required when
+        # updating as well
+        if param_description.options[:action_aware] && param_description.options[:required]
+          param_description.required = true
+        end
+        prepare_hash_params
+      end
+
+      def hash_params_ordered
+        @hash_params_ordered ||= _apipie_dsl_data[:params].map do |args|
+          options = args.find { |arg| arg.is_a? Hash }
+          options[:parent] = self.param_description
+          Apipie::ParamDescription.from_dsl_data(param_description.method_description, args)
+        end
       end
 
       def validate(value)
@@ -198,16 +215,30 @@ module Apipie
         "Must be a Hash"
       end
 
-      def param(param_name, validator, desc_or_options = nil, options = {}, &block)
-        param_description = Apipie::ParamDescription.new(param_name, validator, desc_or_options, options, &block)
-        param_description.parent = self.param_description
-        @hash_params_ordered << param_description
-        @hash_params[param_name.to_sym] = param_description
-      end
-
       def expected_type
         'hash'
       end
+
+      # where the group definition should be looked up when no scope
+      # given. This is expected to return a controller.
+      def _default_param_group_scope
+        @param_group && @param_group[:scope]
+      end
+
+      def merge_with(other_validator)
+        if other_validator.is_a? HashValidator
+          @hash_params_ordered = ParamDescription.unify(self.hash_params_ordered + other_validator.hash_params_ordered)
+          prepare_hash_params
+        else
+          super
+        end
+      end
+
+      def prepare_hash_params
+        @hash_params = hash_params_ordered.reduce({}) do |h, param|
+          h.update(param.name.to_sym => param)
+        end
+      end
     end
 
 

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = '0.0.17'
+  VERSION = '0.0.18'
 end

data/spec/controllers/apipies_controller_spec.rb

@@ -110,10 +110,13 @@ describe Apipie::ApipiesController do
 
       Apipie.configuration.use_cache = true
       Apipie.configuration.cache_dir = cache_dir
+      @orig_version = Apipie.configuration.default_version
       Apipie.configuration.default_version = 'v1'
     end
 
     after do
+      Apipie.configuration.use_cache = false
+      Apipie.configuration.default_version = @orig_version
       # FileUtils.rm_r(cache_dir) if File.exists?(cache_dir)
     end
 

data/spec/controllers/users_controller_spec.rb

@@ -20,6 +20,8 @@ end
 
 describe UsersController do
 
+  let(:dsl_data) { ActionController::Base.send(:_apipie_dsl_data_init) }
+
   describe "resource description" do
     subject do
       Apipie.get_resource_description(UsersController, Apipie.configuration.default_version)
@@ -27,10 +29,10 @@ describe UsersController do
 
     it "should contain all resource methods" do
       methods = subject._methods
-      methods.count.should == 5
       methods.keys.should include(:show)
       methods.keys.should include(:index)
       methods.keys.should include(:create)
+      methods.keys.should include(:update)
       methods.keys.should include(:two_urls)
     end
 
@@ -44,20 +46,11 @@ describe UsersController do
     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)
+      subject._params_args.count.should == 2
+      name, type, options = subject._params_args.first
+      name.should == :id
+      type.should == Fixnum
+      options.should == {:required=>false, :desc=>"User ID"}
     end
   end
 
@@ -162,7 +155,7 @@ describe UsersController do
         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.count.should == 4
         hash_params[0].name == :name
         hash_params[1].name == :pass
         hash_params[2].name == :membership
@@ -425,10 +418,10 @@ EOS2
       end
 
       it "skips the listed  actions from the documentation" do
-        Apipie.define_method_description(UsersController, :ignore)
+        Apipie.define_method_description(UsersController, :ignore, dsl_data)
         Apipie.get_method_description(UsersController, :ignore).should be_nil
 
-        Apipie.define_method_description(UsersController, :dont_ignore)
+        Apipie.define_method_description(UsersController, :dont_ignore, dsl_data)
         Apipie.get_method_description(UsersController, :dont_ignore).should_not be_nil
       end
     end
@@ -439,9 +432,9 @@ EOS2
       end
 
       it "skips the listed controller from the documentation" do
-        Apipie.define_method_description(IgnoredController, :ignore)
+        Apipie.define_method_description(IgnoredController, :ignore, dsl_data)
         Apipie.get_method_description(IgnoredController, :ignore).should be_nil
-        Apipie.define_method_description(IgnoredController, :ignore)
+        Apipie.define_method_description(IgnoredController, :ignore, dsl_data)
         Apipie.get_method_description(IgnoredController, :ignore).should be_nil
       end
     end