apipie-rails 0.0.17 → 0.0.18

data/.gitignore

@@ -5,3 +5,5 @@ spec/dummy/db/*.sqlite3
 spec/dummy/log/*.log
 spec/dummy/tmp/
 .idea
+Gemfile.lock
+.rvmrc

data/CHANGELOG

@@ -2,6 +2,12 @@
  Changelog
 ===========
 
+v0.0.18
+-------
+
+* ``param_group`` and ``def_param_group`` keywords
+* ``:action_aware`` options for reusing param groups for create/update actions
+
 v0.0.17
 -------
 

data/README.rst

@@ -266,6 +266,111 @@ Example:
      #...
    end
 
+DRY with param_group
+--------------------
+
+Often, params occur together in more actions. Typically, most of the
+params for ``create`` and ``update`` actions are common for both of
+them.
+
+This params can be extracted with ``def_param_group`` and
+``param_group`` keywords.
+
+The definition is looked up in the scope of the controller. If the
+group is defined in a different controller, it might be referenced by
+specifying the second argument.
+
+Example:
+~~~~~~~~
+
+.. code:: ruby
+
+   # v1/users_controller.rb
+   def_param_group :address do
+     param :street, String
+     param :number, Integer
+     param :zip, String
+   end
+
+   def_param_group :user do
+     param :user, Hash do
+       param :name, String, "Name of the user"
+       param_group :address
+     end
+   end
+
+   api :POST, "/users", "Create an user"
+   param_group :user
+   def create
+     # ...
+   end
+
+   api :PUT, "/users/:id", "Update an user"
+   param_group :user
+   def update
+     # ...
+   end
+
+   # v2/users_controller.rb
+   api :POST, "/users", "Create an user"
+   param_group :user, V1::UsersController
+   def create
+     # ...
+   end
+
+Action Aware params
+-------------------
+
+In CRUD operations, this pattern occurs quite often: params that need
+to be set are:
+
+* for create action: ``required => true`` and ``allow_nil => false``
+* for update action: ``required => false`` and ``allow_nil => false``
+
+This makes it hard to share the param definitions across theses
+actions. Therefore, you can make the description a bit smarter by
+setting ``:action_aware => true``.
+
+You can specify explicitly how the param group should be evaluated
+with ``:as`` option (either :create  or :update)
+
+Example
+~~~~~~~
+
+.. code:: ruby
+
+   def_param_group :user do
+     param :user, Hash, :action_aware => true do
+       param :name, String, :required => true
+       param :description, :String
+     end
+   end
+
+   api :POST, "/users", "Create an user"
+   param_group :user
+   def create
+     # ...
+   end
+
+   api :PUT, "/users/admin", "Create an admin"
+   param_group :user, :as => :create
+   def create_admin
+     # ...
+   end
+
+   api :PUT, "/users/:id", "Update an user"
+   param_group :user
+   def update
+     # ...
+   end
+
+In this case, ``user[name]`` will be not be allowed nil for all
+actions and required only for ``create`` and ``create_admin``. Params
+with ``allow_nil`` set explicitly don't have this value changed.
+
+Action awareness is being inherited from ancestors (in terms of
+nested params).
+
 
 =========================
  Configuration Reference
@@ -564,7 +669,7 @@ Textile
   Use Apipie::Markup::Textile.new. You need RedCloth gem.
 
 Or provide you own object with ``to_html(text)`` method.
-For inspiration this is how Textile look like:
+For inspiration this is how Textile markup usage looks like:
 
 .. code:: ruby
 

data/lib/apipie-rails.rb

@@ -1,6 +1,7 @@
 require "apipie/routing"
 require "apipie/markup"
 require "apipie/apipie_module"
+require "apipie/dsl_definition"
 require "apipie/configuration"
 require "apipie/method_description"
 require "apipie/resource_description"
@@ -9,7 +10,6 @@ require "apipie/errors"
 require "apipie/error_description"
 require "apipie/see_description"
 require "apipie/validator"
-require "apipie/dsl_definition"
 require "apipie/railtie"
 require 'apipie/extractor'
 require "apipie/version"

data/lib/apipie/application.rb

@@ -12,14 +12,11 @@ module Apipie
       end
     end
 
-    attr_accessor :last_dsl_data
-
     attr_reader :resource_descriptions
 
     def initialize
       super
       init_env
-      clear_last
     end
 
     def available_versions
@@ -31,10 +28,11 @@ module Apipie
     end
 
     # create new method api description
-    def define_method_description(controller, method_name, versions = [])
+    def define_method_description(controller, method_name, dsl_data)
       return if ignored?(controller, method_name)
       ret_method_description = nil
 
+      versions = dsl_data[:api_versions] || []
       versions = controller_versions(controller) if versions.empty?
 
       versions.each do |version|
@@ -45,7 +43,7 @@ module Apipie
           resource_description = define_resource_description(controller, version)
         end
 
-        method_description = Apipie::MethodDescription.new(method_name, resource_description, self)
+        method_description = Apipie::MethodDescription.new(method_name, resource_description, dsl_data)
 
         # we create separate method description for each version in
         # case the method belongs to more versions. We return just one
@@ -95,17 +93,18 @@ module Apipie
       @controller_versions[controller] = versions
     end
 
-    def add_method_description_args(method, path, desc)
-      @last_dsl_data[:api_args] << MethodDescription::Api.new(method, path, desc)
-    end
-
-    def add_example(example)
-      @last_dsl_data[:examples] << example.strip_heredoc
+    def add_param_group(controller, name, &block)
+      key = "#{controller.controller_path}##{name}"
+      @param_groups[key] = block
     end
 
-    # check if there is some saved description
-    def apipie_provided?
-      true unless last_dsl_data[:api_args].blank?
+    def get_param_group(controller, name)
+      key = "#{controller.controller_path}##{name}"
+      if @param_groups.has_key?(key)
+        return @param_groups[key]
+      else
+        raise "param group #{key} not defined"
+      end
     end
 
     # get api for given method
@@ -198,25 +197,11 @@ module Apipie
     def init_env
       @resource_descriptions = HashWithIndifferentAccess.new { |h, version| h[version] = {} }
       @controller_to_resource_id = {}
+      @param_groups = {}
 
       # what versions does the controller belong in (specified by resource_description)?
       @controller_versions = Hash.new { |h, controller| h[controller] = [] }
     end
-    # clear all saved data
-    def clear_last
-      @last_dsl_data = {
-        :api_args          => [],
-        :errors            => [],
-        :params            => [],
-        :resouce_id        => nil,
-        :short_description => nil,
-        :description       => nil,
-        :examples          => [],
-        :see               => [],
-        :formats           => nil,
-        :api_versions      => []
-      }
-    end
 
     def recorded_examples
       return @recorded_examples if @recorded_examples

data/lib/apipie/dsl_definition.rb

@@ -5,45 +5,36 @@ module Apipie
   # DSL is a module that provides #api, #error, #param, #error.
   module DSL
 
-    attr_reader :apipie_resource_descriptions
-
-    private
-
-    # Describe whole resource
-    #
-    # Example:
-    # api :desc => "Show user profile", :path => "/users/", :version => '1.0 - 3.4.2012'
-    # param :id, Fixnum, :desc => "User ID", :required => true
-    # desc <<-EOS
-    #   Long description...
-    # EOS
-    def resource_description(options = {}, &block) #:doc:
-      return unless Apipie.active_dsl?
-      raise ArgumentError, "Block expected" unless block_given?
-
-      dsl_data = ResourceDescriptionDsl.eval_dsl(self, &block)
-      versions = dsl_data[:api_versions]
-      @apipie_resource_descriptions = versions.map do |version|
-        Apipie.define_resource_description(self, version, dsl_data)
-      end
-      Apipie.set_controller_versions(self, versions)
-    end
+    module Base
+      attr_reader :apipie_resource_descriptions
 
-    class ResourceDescriptionDsl
-      include Apipie::DSL
+      private
 
-      NO_RESOURCE_KEYWORDS = %w[api see example]
+      def _apipie_dsl_data
+        @_apipie_dsl_data ||= _apipie_dsl_data_init
+      end
 
-      NO_RESOURCE_KEYWORDS.each do |method|
-        define_method method do
-          raise "#{method} is not defined for resource description"
-        end
+      def _apipie_dsl_data_clear
+        @_apipie_dsl_data = nil
       end
 
-      def initialize(controller)
-        @controller = controller
+      def _apipie_dsl_data_init
+        @_apipie_dsl_data =  {
+         :api_args          => [],
+         :errors            => [],
+         :params            => [],
+         :resouce_id        => nil,
+         :short_description => nil,
+         :description       => nil,
+         :examples          => [],
+         :see               => [],
+         :formats           => nil,
+         :api_versions      => []
+       }
       end
+    end
 
+    module Resource
       # by default, the resource id is derived from controller_name
       # it can be overwritten with.
       #
@@ -53,171 +44,248 @@ module Apipie
       end
 
       def name(name)
-        Apipie.last_dsl_data[:resource_name] = name
+        _apipie_dsl_data[:resource_name] = name
       end
 
       def api_base_url(url)
-        Apipie.last_dsl_data[:api_base_url] = url
+        _apipie_dsl_data[:api_base_url] = url
       end
 
       def short(short)
-        Apipie.last_dsl_data[:short_description] = short
+        _apipie_dsl_data[:short_description] = short
       end
       alias :short_description :short
 
       def path(path)
-        Apipie.last_dsl_data[:path] = path
+        _apipie_dsl_data[:path] = path
       end
 
       def app_info(app_info)
-        Apipie.last_dsl_data[:app_info] = app_info
+        _apipie_dsl_data[:app_info] = app_info
       end
+    end
 
-      # evaluates resource description DSL and returns results
-      def self.eval_dsl(controller, &block)
-        self.new(controller).instance_eval(&block)
-        dsl_data = Apipie.last_dsl_data
-        if dsl_data[:api_versions].empty?
-          dsl_data[:api_versions] = Apipie.controller_versions(controller)
+    module Action
+
+      def def_param_group(name, &block)
+        Apipie.add_param_group(self, name, &block)
+      end
+
+      # Declare an api.
+      #
+      # Example:
+      #   api :GET, "/resource_route", "short description",
+      #
+      def api(method, path, desc = nil) #:doc:
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:api_args] << [method, path, desc]
+      end
+
+      # Reference other similar method
+      #
+      #   api :PUT, '/articles/:id'
+      #   see "articles#create"
+      #   def update; end
+      def see(*args)
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:see] << args
+      end
+
+      # Show some example of what does the described
+      # method return.
+      def example(example) #:doc:
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:examples] << example.strip_heredoc
+      end
+
+      # Describe whole resource
+      #
+      # Example:
+      # api :desc => "Show user profile", :path => "/users/", :version => '1.0 - 3.4.2012'
+      # param :id, Fixnum, :desc => "User ID", :required => true
+      # desc <<-EOS
+      #   Long description...
+      # EOS
+      def resource_description(options = {}, &block) #:doc:
+        return unless Apipie.active_dsl?
+        raise ArgumentError, "Block expected" unless block_given?
+
+        dsl_data = ResourceDescriptionDsl.eval_dsl(self, &block)
+        versions = dsl_data[:api_versions]
+        @apipie_resource_descriptions = versions.map do |version|
+          Apipie.define_resource_description(self, version, dsl_data)
         end
-        dsl_data
-      ensure
-        Apipie.clear_last
+        Apipie.set_controller_versions(self, versions)
       end
-    end
 
+      # create method api and redefine newly added method
+      def method_added(method_name) #:doc:
+        super
 
-    # Declare an api.
-    #
-    # Example:
-    #   api :GET, "/resource_route", "short description",
-    #
-    def api(method, path, desc = nil) #:doc:
-      return unless Apipie.active_dsl?
-      Apipie.add_method_description_args(method, path, desc)
-    end
+        if ! Apipie.active_dsl? || _apipie_dsl_data[:api_args].blank?
+          _apipie_dsl_data_clear
+          return
+        end
 
-    def api_versions(*versions)
-      Apipie.last_dsl_data[:api_versions].concat(versions)
-    end
-    alias :api_version :api_versions
-
-    # Describe the next method.
-    #
-    # Example:
-    #   desc "print hello world"
-    #   def hello_world
-    #     puts "hello world"
-    #   end
-    #
-    def desc(description) #:doc:
-      return unless Apipie.active_dsl?
-      if Apipie.last_dsl_data[:description]
-        raise "Double method description."
-      end
-      Apipie.last_dsl_data[:description] = description
-    end
-    alias :description :desc
-    alias :full_description :desc
-
-    # Reference other similar method
-    #
-    #   api :PUT, '/articles/:id'
-    #   see "articles#create"
-    #   def update; end
-    def see(*args)
-      return unless Apipie.active_dsl?
-      Apipie.last_dsl_data[:see] << Apipie::SeeDescription.new(args)
-    end
+        begin
+          # remove method description if exists and create new one
+          Apipie.remove_method_description(self, _apipie_dsl_data[:api_versions], method_name)
+          description = Apipie.define_method_description(self, method_name, _apipie_dsl_data)
+        ensure
+          _apipie_dsl_data_clear
+        end
 
-    # Show some example of what does the described
-    # method return.
-    def example(example) #:doc:
-      return unless Apipie.active_dsl?
-      Apipie.add_example(example)
-    end
+        # redefine method only if validation is turned on
+        if description && Apipie.configuration.validate == true
 
-    # Describe available request/response formats
-    #
-    #   formats ['json', 'jsonp', 'xml']
-    def formats(formats) #:doc:
-      return unless Apipie.active_dsl?
-      Apipie.last_dsl_data[:formats] = formats
-    end
+          old_method = instance_method(method_name)
 
-    # Describe possible errors
-    #
-    # Example:
-    #   error :desc => "speaker is sleeping", :code => 500
-    #   error 500, "speaker is sleeping"
-    #   def hello_world
-    #     return 500 if self.speaker.sleeping?
-    #     puts "hello world"
-    #   end
-    #
-    def error(*args) #:doc:
-      return unless Apipie.active_dsl?
-      Apipie.last_dsl_data[:errors] << Apipie::ErrorDescription.new(args)
-    end
+          define_method(method_name) do |*args|
 
-    # Describe method's parameter
-    #
-    # Example:
-    #   param :greeting, String, :desc => "arbitrary text", :required => true
-    #   def hello_world(greeting)
-    #     puts greeting
-    #   end
-    #
-    def param(param_name, validator, desc_or_options = nil, options = {}, &block) #:doc:
-      return unless Apipie.active_dsl?
-      Apipie.last_dsl_data[:params] << Apipie::ParamDescription.new(param_name, validator, desc_or_options, options, &block)
+            if Apipie.configuration.validate == true
+              description.params.each do |_, param|
+
+                # check if required parameters are present
+                if param.required && !params.has_key?(param.name)
+                  raise ParamMissing.new(param.name)
+                end
+
+                # params validations
+                if params.has_key?(param.name)
+                  param.validate(params[:"#{param.name}"])
+                end
+
+              end
+            end
+
+            # run the original method code
+            old_method.bind(self).call(*args)
+          end
+
+        end
+      end # def method_added
     end
 
-    # create method api and redefine newly added method
-    def method_added(method_name) #:doc:
-      super
+    module Common
+      def api_versions(*versions)
+        _apipie_dsl_data[:api_versions].concat(versions)
+      end
+      alias :api_version :api_versions
 
-      if ! Apipie.active_dsl? || ! Apipie.apipie_provided?
-        Apipie.clear_last
-        return
+      # Describe the next method.
+      #
+      # Example:
+      #   desc "print hello world"
+      #   def hello_world
+      #     puts "hello world"
+      #   end
+      #
+      def desc(description) #:doc:
+        return unless Apipie.active_dsl?
+        if _apipie_dsl_data[:description]
+          raise "Double method description."
+        end
+        _apipie_dsl_data[:description] = description
       end
+      alias :description :desc
+      alias :full_description :desc
 
-      begin
-        # remove method description if exists and create new one
-        Apipie.remove_method_description(self, Apipie.last_dsl_data[:api_versions], method_name)
-        description = Apipie.define_method_description(self, method_name, Apipie.last_dsl_data[:api_versions])
-      ensure
-        Apipie.clear_last
+      # Describe available request/response formats
+      #
+      #   formats ['json', 'jsonp', 'xml']
+      def formats(formats) #:doc:
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:formats] = formats
       end
 
-      # redefine method only if validation is turned on
-      if description && Apipie.configuration.validate == true
+      # Describe possible errors
+      #
+      # Example:
+      #   error :desc => "speaker is sleeping", :code => 500
+      #   error 500, "speaker is sleeping"
+      #   def hello_world
+      #     return 500 if self.speaker.sleeping?
+      #     puts "hello world"
+      #   end
+      #
+      def error(*args) #:doc:
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:errors] << args
+      end
 
-        old_method = instance_method(method_name)
+    end
 
-        define_method(method_name) do |*args|
+    # this describes the params, it's in separate module because it's
+    # used in Validators as well
+    module Param
+      # Describe method's parameter
+      #
+      # Example:
+      #   param :greeting, String, :desc => "arbitrary text", :required => true
+      #   def hello_world(greeting)
+      #     puts greeting
+      #   end
+      #
+      def param(param_name, validator, desc_or_options = nil, options = {}, &block) #:doc:
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:params] << [param_name,
+                                      validator,
+                                      desc_or_options,
+                                      options.merge(:param_group => @_current_param_group),
+                                      block]
+      end
 
-          if Apipie.configuration.validate == true
-            description.params.each do |_, param|
+      # Reuses param group for this method. The definition is looked up
+      # in scope of this controller. If the group was defined in
+      # different controller, the second param can be used to specify it.
+      # when using action_aware parmas, you can specify :as =>
+      # :create or :update to explicitly say how it should behave
+      def param_group(name, scope_or_options = nil, options = {})
+        if scope_or_options.is_a? Hash
+          options.merge!(scope_or_options)
+          scope = options[:scope]
+        else
+          scope = scope_or_options
+        end
+        scope ||= _default_param_group_scope
+        @_current_param_group = {:scope => scope, :name => name, :options => options}
+        self.instance_exec(&Apipie.get_param_group(scope, name))
+      ensure
+        @_current_param_group = nil
+      end
 
-              # check if required parameters are present
-              if param.required && !params.has_key?(param.name)
-                raise ParamMissing.new(param.name)
-              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
+        self
+      end
+    end
 
-              # params validations
-              if params.has_key?(param.name)
-                param.validate(params[:"#{param.name}"])
-              end
+    class ResourceDescriptionDsl
+      include Apipie::DSL::Base
+      include Apipie::DSL::Common
+      include Apipie::DSL::Resource
+      include Apipie::DSL::Param
 
-            end
-          end
+      def initialize(controller)
+        @controller = controller
+      end
 
-          # run the original method code
-          old_method.bind(self).call(*args)
-        end
 
+      def _eval_dsl(&block)
+        instance_eval(&block)
+        return _apipie_dsl_data
       end
-    end # def method_added
+
+      # evaluates resource description DSL and returns results
+      def self.eval_dsl(controller, &block)
+        dsl_data  = self.new(controller)._eval_dsl(&block)
+        if dsl_data[:api_versions].empty?
+          dsl_data[:api_versions] = Apipie.controller_versions(controller)
+        end
+        dsl_data
+      end
+    end
+
   end # module DSL
 end # module Apipie