apipie-rails 0.0.19 → 0.0.20

data/CHANGELOG

@@ -2,6 +2,14 @@
  Changelog
 ===========
 
+v0.0.20
+-------
+
+* namespaced resources - prevent collisions when one resource defined
+  in more modules
+* ``Apipie::DSL::Concern`` for being able to use the DSL in module
+  that is included into controllers
+
 v0.0.19
 -------
 

data/README.rst

@@ -371,6 +371,85 @@ with ``allow_nil`` set explicitly don't have this value changed.
 Action awareness is being inherited from ancestors (in terms of
 nested params).
 
+Concerns
+--------
+
+Sometimes, the actions are not defined in the controller class
+directly but included from a module instead. You can load the Apipie
+DSL into the module by extending it with ``Apipie::DSL::Concern``.
+
+The module can be used in more controllers. Therefore there is a way
+how to substitute parts of the documentation in the module with controller
+specific values. The substitutions can be stated explicitly with
+``apipie_concern_subst(:key => "value")`` (needs to be called before
+the module is included to take effect). The substitutions are
+performed in paths and descriptions of APIs and names and descriptions
+of params.
+
+There are some default substitutions available:
+
+:controller_path
+  value of ``controller.controller_path``, e.g. ``api/users`` for
+  ``Api::UsersController``
+
+:resource_id
+  Apipie identifier of the resource, e.g. ``users`` for
+  ``Api::UsersController`` or set by ``resource_id``
+
+Example
+~~~~~~~
+
+.. code:: ruby
+
+   # users_module.rb
+   module UsersModule
+     extend Apipie::DSL::Concern
+
+     api :GET, '/:controller_path', 'List :resource_id'
+     def index
+       # ...
+     end
+
+     api :GET, '/:resource_id/:id', 'Show a :resource'
+     def show
+       # ...
+     end
+
+     api :POST, '/:resource_id', "Create a :resource"
+     param :concern, Hash, :required => true
+       param :name, String, 'Name of a :resource'
+       param :resource_type, ['standard','vip']
+     end
+     def create
+       # ...
+     end
+
+     api :GET, '/:resource_id/:custom_subst'
+     def custom
+       # ...
+     end
+   end
+
+   # users_controller.rb
+   class UsersController < ApplicationController
+
+     resource_description { resource_id 'customers' }
+
+     apipie_concern_subst(:custom_subst => 'custom', :resource => 'customer')
+     include UsersModule
+
+     # the following paths are documented
+     # api :GET, '/users'
+     # api :GET, '/customers/:id', 'Show a customer'
+     # api :POST, '/customers', 'Create a customer'
+     #   param :customer, :required => true do
+     #     param :name, String, 'Name of a customer'
+     #     param :customer_type, ['standard', 'vip']
+     #   end
+     # api :GET, '/customers/:custom'
+   end
+
+
 
 =========================
  Configuration Reference
@@ -427,6 +506,10 @@ ignored
   to be ignored when generationg the documentation
   e.g. ``%w[Api::CommentsController Api::PostsController#post]``
 
+namespaced_resources
+  Use controller paths instead of controller names as resource id.
+  This prevents same named controllers overwriting each other.
+
 
 Example:
 

data/lib/apipie/application.rb

@@ -94,12 +94,12 @@ module Apipie
     end
 
     def add_param_group(controller, name, &block)
-      key = "#{controller.controller_path}##{name}"
+      key = "#{controller.name}##{name}"
       @param_groups[key] = block
     end
 
     def get_param_group(controller, name)
-      key = "#{controller.controller_path}##{name}"
+      key = "#{controller.name}##{name}"
       if @param_groups.has_key?(key)
         return @param_groups[key]
       else
@@ -276,6 +276,10 @@ module Apipie
         klass
       elsif @controller_to_resource_id.has_key?(klass)
         @controller_to_resource_id[klass]
+      elsif Apipie.configuration.namespaced_resources? && klass.respond_to?(:controller_path)
+        return nil if klass == ActionController::Base
+        path = klass.controller_path
+        path.gsub(version_prefix(klass), "").gsub("/", "-")
       elsif klass.respond_to?(:controller_name)
         return nil if klass == ActionController::Base
         klass.controller_name
@@ -286,6 +290,12 @@ module Apipie
 
     private
 
+    def version_prefix(klass)
+      version = controller_versions(klass).first
+      path = Apipie.configuration.api_base_url[version]
+      path[1..-1] + "/"
+    end
+
     def get_resource_version(resource_description)
       if resource_description.respond_to? :_version
         resource_description._version

data/lib/apipie/configuration.rb

@@ -3,10 +3,11 @@ module Apipie
 
     attr_accessor :app_name, :app_info, :copyright, :markup, :disqus_shortname,
       :validate, :api_base_url, :doc_base_url, :required_by_default, :layout,
-      :default_version, :debug, :version_in_url
+      :default_version, :debug, :version_in_url, :namespaced_resources
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
+    alias_method :namespaced_resources?, :namespaced_resources
 
     # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
     #
@@ -107,6 +108,7 @@ module Apipie
       @default_version = "1.0"
       @debug = false
       @version_in_url = true
+      @namespaced_resources = false
     end
   end
 end

data/lib/apipie/dsl_definition.rb

@@ -118,52 +118,6 @@ module Apipie
         Apipie.set_controller_versions(self, versions)
       end
 
-      # create method api and redefine newly added method
-      def method_added(method_name) #:doc:
-        super
-
-        if ! Apipie.active_dsl? || _apipie_dsl_data[:api_args].blank?
-          _apipie_dsl_data_clear
-          return
-        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
-
-        # redefine method only if validation is turned on
-        if description && Apipie.configuration.validate == true
-
-          old_method = instance_method(method_name)
-
-          define_method(method_name) do |*args|
-
-            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
 
     module Common
@@ -213,6 +167,38 @@ module Apipie
         _apipie_dsl_data[:errors] << args
       end
 
+      def _apipie_define_validators(description)
+        # redefine method only if validation is turned on
+        if description && Apipie.configuration.validate == true
+
+          old_method = instance_method(description.method)
+
+          define_method(description.method) do |*args|
+
+            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
+
     end
 
     # this describes the params, it's in separate module because it's
@@ -261,6 +247,111 @@ module Apipie
       end
     end
 
+    module Controller
+      include Apipie::DSL::Base
+      include Apipie::DSL::Common
+      include Apipie::DSL::Action
+      include Apipie::DSL::Param
+
+      # defines the substitutions to be made in the API paths deifned
+      # in concerns included. For example:
+      #
+      # There is this method defined in concern:
+      #
+      #    api GET ':controller_path/:id'
+      #    def show
+      #      # ...
+      #    end
+      #
+      # If you include the concern into some controller, you can
+      # specify the value for :controller_path like this:
+      #
+      #      apipie_concern_subst(:controller_path => '/users')
+      #      include ::Concerns::SampleController
+      #
+      # The resulting path will be '/users/:id'.
+      #
+      # It has to be specified before the concern is included.
+      #
+      # If not specified, the default predefined substitions are
+      #
+      #    {:conroller_path => controller.controller_path,
+      #     :resource_id  => `resource_id_from_apipie` }
+      def apipie_concern_subst(subst_hash)
+        _apipie_concern_subst.merge!(subst_hash)
+      end
+
+      def _apipie_concern_subst
+        @_apipie_concern_subst ||= {:controller_path => self.controller_path,
+                                    :resource_id => Apipie.get_resource_name(self)}
+      end
+
+      def _apipie_perform_concern_subst(string)
+        return _apipie_concern_subst.reduce(string) do |ret, (key, val)|
+          ret.gsub(":#{key}", val)
+        end
+      end
+
+      # create method api and redefine newly added method
+      def method_added(method_name) #:doc:
+        super
+
+        if ! Apipie.active_dsl? || _apipie_dsl_data[:api_args].blank?
+          _apipie_dsl_data_clear
+          return
+        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
+
+        _apipie_define_validators(description)
+      end # def method_added
+    end
+
+    module Concern
+      include Apipie::DSL::Base
+      include Apipie::DSL::Common
+      include Apipie::DSL::Action
+      include Apipie::DSL::Param
+
+      # the concern was included into a controller
+      def included(controller)
+        super
+        _apipie_concern_data.each do |method_name, _apipie_dsl_data|
+          # remove method description if exists and create new one
+          description = Apipie.define_method_description(controller, method_name, _apipie_dsl_data)
+          controller._apipie_define_validators(description)
+        end
+      end
+
+      def _apipie_concern_data
+        @_apipie_concern_data ||= []
+      end
+
+      # create method api and redefine newly added method
+      def method_added(method_name) #:doc:
+        super
+
+        if ! Apipie.active_dsl? || _apipie_dsl_data[:api_args].blank?
+          _apipie_dsl_data_clear
+          return
+        end
+
+        begin
+          _apipie_concern_data << [method_name, _apipie_dsl_data.merge(:from_concern => true)]
+        ensure
+          _apipie_dsl_data_clear
+        end
+
+      end # def method_added
+
+    end
+
     class ResourceDescriptionDsl
       include Apipie::DSL::Base
       include Apipie::DSL::Common
@@ -271,7 +362,6 @@ module Apipie
         @controller = controller
       end
 
-
       def _eval_dsl(&block)
         instance_eval(&block)
         return _apipie_dsl_data

data/lib/apipie/method_description.rb

@@ -20,9 +20,10 @@ module Apipie
     def initialize(method, resource, dsl_data)
       @method = method.to_s
       @resource = resource
+      @from_concern = dsl_data[:from_concern]
 
       @apis = dsl_data[:api_args].map do |method, path, desc|
-        MethodDescription::Api.new(method, path, desc)
+        MethodDescription::Api.new(method, concern_subst(path), concern_subst(desc))
       end
 
       desc = dsl_data[:description] || ''
@@ -137,6 +138,11 @@ module Apipie
       }
     end
 
+    # was the description defines in a module instead of directly in controller?
+    def from_concern?
+      @from_concern
+    end
+
     private
 
     def merge_params(params, new_params)
@@ -171,6 +177,15 @@ module Apipie
       example
     end
 
+    def concern_subst(string)
+      return if string.nil?
+      if from_concern?
+        resource.controller._apipie_perform_concern_subst(string)
+      else
+        string
+      end
+    end
+
   end
 
 end

data/lib/apipie/param_description.rb

@@ -38,8 +38,8 @@ module Apipie
       @options = options
 
       @method_description = method_description
-      @name = name
-      @desc = Apipie.markup_to_html(@options[:desc] || '')
+      @name = concern_subst(name)
+      @desc = concern_subst(Apipie.markup_to_html(@options[:desc] || ''))
       @parent = @options[:parent]
       @required = if @options.has_key? :required
         @options[:required]
@@ -179,6 +179,19 @@ module Apipie
       end
     end
 
+    def concern_subst(string)
+      return if string.nil?
+      original = string
+      if method_description.from_concern?
+        string = ":#{original}" if original.is_a? Symbol
+        ret = method_description.resource.controller._apipie_perform_concern_subst(string)
+        ret = ret.to_sym if original.is_a? Symbol
+        ret
+      else
+        string
+      end
+    end
+
   end
 
 end

data/lib/apipie/railtie.rb

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

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = '0.0.19'
+  VERSION = '0.0.20'
 end

data/spec/controllers/concerns_controller_spec.rb

@@ -0,0 +1,42 @@
+require "spec_helper"
+
+describe ConcernsController do
+
+  it "displays is every controller the concern is included" do
+    Apipie["concern_resources#index"].should be
+    Apipie["concern_resources#show"].should be
+  end
+
+  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
+
+  it "peserved the order of methods being defined in file" do
+    doc_methods = Apipie.get_resource_description('concern_resources')._methods.keys
+    doc_methods.should == [:index, :show, :create, :update, :custom]
+  end
+
+  it "replaces a placeholder doc specified in concern with a real path" do
+    path = Apipie["concern_resources#index"].apis.first.path
+    path.should == '/concerns'
+
+    path = Apipie["concern_resources#show"].apis.first.path
+    path.should == '/concern_resources/:id'
+
+    path = Apipie["concern_resources#custom"].apis.first.path
+    path.should == '/concern_resources/custom'
+  end
+
+  it "replaces placeholders in param names and descriptions" do
+    create_desc = Apipie["concern_resources#create"].params[:user]
+    name_param, concern_type_param = create_desc.validator.hash_params_ordered
+    name_param.desc.should include "Name of a user"
+    concern_type_param.name.should == :user_type
+  end
+end
+

data/spec/dummy/app/controllers/api/v2/nested/architectures_controller.rb

@@ -0,0 +1,30 @@
+module Api
+  module V2
+    class Nested::ArchitecturesController < V2::BaseController
+      resource_description { name 'Architectures' }
+      api :GET, "/nested/architectures/", "List all nested architectures."
+      def index
+      end
+
+      api :GET, "/nested/architectures/:id/", "Show a nested architecture."
+      def show
+      end
+
+      api :POST, "/nested/architectures/", "Create a nested architecture."
+      param_group :arch, Api::V1::ArchitecturesController
+      def create
+      end
+
+      api :PUT, "/nested/architectures/:id/", "Update a nested architecture."
+      param :architecture, Hash, :required => true do
+        param :name, String
+      end
+      def update
+      end
+
+      api :DELETE, "/architecturess/:id/", "Delete a nested architecture."
+      def destroy
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/concerns/sample_controller.rb

@@ -0,0 +1,39 @@
+module Concerns::SampleController
+  extend Apipie::DSL::Concern
+
+  api :GET, '/:controller_path'
+  def index
+    render :text => "OK #{params.inspect}"
+  end
+
+  api :GET, '/:resource_id/:id'
+  param :id, String
+  def show
+    render :text => "OK #{params.inspect}"
+  end
+
+  def_param_group :concern do
+    param :concern, Hash, :required => true, :action_aware => true do
+      param :name, String, "Name of a :concern"
+      param :concern_type, String
+    end
+  end
+
+  api :POST, '/:resource_id', "Create a :concern"
+  param_group :concern
+  def create
+    render :text => "OK #{params.inspect}"
+  end
+
+  api :PUT, '/:resource_id/:id'
+  param :id, String
+  param_group :concern
+  def update
+    render :text => "OK #{params.inspect}"
+  end
+
+  api :GET, '/:resource_id/:custom_subst'
+  def custom
+    render :text => "OK #{params.inspect}"
+  end
+end

data/spec/dummy/app/controllers/concerns_controller.rb

@@ -0,0 +1,8 @@
+class ConcernsController < ApplicationController
+
+  resource_description { resource_id 'concern_resources' }
+
+  apipie_concern_subst(:concern => 'user', :custom_subst => 'custom')
+  include ::Concerns::SampleController
+
+end

data/spec/dummy/config/routes.rb

@@ -1,9 +1,10 @@
 Dummy::Application.routes.draw do
 
   scope ENV['RAILS_RELATIVE_URL_ROOT'] || '/' do
-    
+
     scope '/api' do
       resources :users
+      resources :concerns, :only => [:index, :show]
       resources :twitter_example do
         collection do
           get :lookup

data/spec/lib/application_spec.rb

@@ -0,0 +1,23 @@
+require "spec_helper"
+
+describe Apipie::Application do
+
+  describe "get_resource_name" do
+    subject {Apipie.get_resource_name(Api::V2::Nested::ArchitecturesController)}
+    context "with namespaced_resources enabled" do
+      before { Apipie.configuration.namespaced_resources = true }
+
+      it "should not overwrite the parent resource" do
+        subject.should_not eq(Apipie.get_resource_name(Api::V2::ArchitecturesController))
+      end
+    end
+
+    context "with namespaced_resources enabled" do
+      before { Apipie.configuration.namespaced_resources = false }
+
+      it "should overwrite the the parent" do
+        subject.should eq(Apipie.get_resource_name(Api::V2::ArchitecturesController))
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apipie-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.19
+  version: 0.0.20
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-13 00:00:00.000000000 Z
+date: 2013-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -198,6 +198,7 @@ files:
 - spec/controllers/api/v2/architectures_controller_spec.rb
 - spec/controllers/api/v2/nested/resources_controller_spec.rb
 - spec/controllers/apipies_controller_spec.rb
+- spec/controllers/concerns_controller_spec.rb
 - spec/controllers/users_controller_spec.rb
 - spec/dummy/Rakefile
 - spec/dummy/app/controllers/api/base_controller.rb
@@ -205,8 +206,11 @@ files:
 - spec/dummy/app/controllers/api/v1/base_controller.rb
 - spec/dummy/app/controllers/api/v2/architectures_controller.rb
 - spec/dummy/app/controllers/api/v2/base_controller.rb
+- spec/dummy/app/controllers/api/v2/nested/architectures_controller.rb
 - spec/dummy/app/controllers/api/v2/nested/resources_controller.rb
 - spec/dummy/app/controllers/application_controller.rb
+- spec/dummy/app/controllers/concerns/sample_controller.rb
+- spec/dummy/app/controllers/concerns_controller.rb
 - spec/dummy/app/controllers/twitter_example_controller.rb
 - spec/dummy/app/controllers/users_controller.rb
 - spec/dummy/app/views/layouts/application.html.erb
@@ -240,6 +244,7 @@ files:
 - spec/dummy/public/javascripts/rails.js
 - spec/dummy/public/stylesheets/.gitkeep
 - spec/dummy/script/rails
+- spec/lib/application_spec.rb
 - spec/lib/method_description_spec.rb
 - spec/lib/param_description_spec.rb
 - spec/lib/param_group_spec.rb
@@ -274,6 +279,7 @@ test_files:
 - spec/controllers/api/v2/architectures_controller_spec.rb
 - spec/controllers/api/v2/nested/resources_controller_spec.rb
 - spec/controllers/apipies_controller_spec.rb
+- spec/controllers/concerns_controller_spec.rb
 - spec/controllers/users_controller_spec.rb
 - spec/dummy/Rakefile
 - spec/dummy/app/controllers/api/base_controller.rb
@@ -281,8 +287,11 @@ test_files:
 - spec/dummy/app/controllers/api/v1/base_controller.rb
 - spec/dummy/app/controllers/api/v2/architectures_controller.rb
 - spec/dummy/app/controllers/api/v2/base_controller.rb
+- spec/dummy/app/controllers/api/v2/nested/architectures_controller.rb
 - spec/dummy/app/controllers/api/v2/nested/resources_controller.rb
 - spec/dummy/app/controllers/application_controller.rb
+- spec/dummy/app/controllers/concerns/sample_controller.rb
+- spec/dummy/app/controllers/concerns_controller.rb
 - spec/dummy/app/controllers/twitter_example_controller.rb
 - spec/dummy/app/controllers/users_controller.rb
 - spec/dummy/app/views/layouts/application.html.erb
@@ -316,6 +325,7 @@ test_files:
 - spec/dummy/public/javascripts/rails.js
 - spec/dummy/public/stylesheets/.gitkeep
 - spec/dummy/script/rails
+- spec/lib/application_spec.rb
 - spec/lib/method_description_spec.rb
 - spec/lib/param_description_spec.rb
 - spec/lib/param_group_spec.rb