jmoses_apipie-rails 0.0.23

data/lib/apipie/configuration.rb

@@ -0,0 +1,128 @@
+module Apipie
+  class Configuration
+
+    attr_accessor :app_name, :app_info, :copyright, :markup, :disqus_shortname,
+      :api_base_url, :doc_base_url, :required_by_default, :layout,
+      :default_version, :debug, :version_in_url, :namespaced_resources,
+      :validate, :validate_value, :validate_presence
+
+
+    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.
+    #
+    #   "#{Rails.root}/app/controllers/api/*.rb"
+    attr_accessor :api_controllers_matcher
+
+    # set to true if you want to reload the controllers at each refresh of the
+    # documentation. It requires +:api_controllers_matcher+ to be set to work
+    # properly.
+    attr_writer :reload_controllers
+
+    def reload_controllers?
+      @reload_controllers = Rails.env.development? unless defined? @reload_controllers
+      return @reload_controllers && @api_controllers_matcher
+    end
+
+    def validate_value
+      return (validate? && @validate_value)
+    end
+    alias_method :validate_value?, :validate_value
+
+    def validate_presence
+      return (validate? && @validate_presence)
+    end
+    alias_method :validate_presence?, :validate_presence
+
+    # set to true if you want to use pregenerated documentation cache and avoid
+    # generating the documentation on runtime (usefull for production
+    # environment).
+    # You can generate the cache by running
+    #
+    #     rake apipie:cache
+    attr_accessor :use_cache
+    alias_method :use_cache?, :use_cache
+
+    attr_writer :cache_dir
+    def cache_dir
+      @cache_dir ||= File.join(Rails.root, "public", "apipie-cache")
+    end
+
+    # if there is not obvious reason why the DSL should be turned on (no
+    # validations, cache turned on etc.), it's disabled to avoid unneeded
+    # allocation. It you need the DSL for other reasons, you can force the
+    # activation.
+    attr_writer :force_dsl
+    def force_dsl?
+      @force_dsl
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when extracting description form calls.
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored_by_recorder
+    def ignored_by_recorder
+      @ignored_by_recorder ||= []
+      @ignored_by_recorder.map(&:to_s)
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when generationg the documentation
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored
+    def ignored
+      @ignored ||= []
+      @ignored.map(&:to_s)
+    end
+
+    # comment to put before docs that was generated automatically. It's used to
+    # determine if the description should be overwritten next recording.
+    # If you want to keep the documentation (prevent from overriding), remove
+    # the line above the docs.
+    attr_writer :generated_doc_disclaimer
+    def generated_doc_disclaimer
+      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENARATING NEXT TIME"
+    end
+
+    def use_disqus?
+      !@disqus_shortname.blank?
+    end
+
+    # set app description for default version
+    # to maintain backward compatibility
+    # new way: config.app_info[version] = description
+    def app_info=(description)
+      version = Apipie.configuration.default_version
+      @app_info[version] = description
+    end
+
+    # set base url for default version of API
+    # to set it for specific version use
+    # config.api_base_url[version] = url
+    def api_base_url=(url)
+      version = Apipie.configuration.default_version
+      @api_base_url[version] = url
+    end
+
+    def initialize
+      @markup = Apipie::Markup::RDoc.new
+      @app_name = "Another API"
+      @app_info = HashWithIndifferentAccess.new
+      @copyright = nil
+      @validate = true
+      @validate_value = true
+      @validate_presence = true
+      @required_by_default = false
+      @api_base_url = HashWithIndifferentAccess.new
+      @doc_base_url = "/apipie"
+      @layout = "apipie/apipie"
+      @disqus_shortname = nil
+      @default_version = "1.0"
+      @debug = false
+      @version_in_url = true
+      @namespaced_resources = false
+    end
+  end
+end

data/lib/apipie/dsl_definition.rb

@@ -0,0 +1,379 @@
+# Apipie DSL functions.
+
+module Apipie
+
+  # DSL is a module that provides #api, #error, #param, #error.
+  module DSL
+
+    module Base
+      attr_reader :apipie_resource_descriptions
+
+      private
+
+      def _apipie_dsl_data
+        @_apipie_dsl_data ||= _apipie_dsl_data_init
+      end
+
+      def _apipie_dsl_data_clear
+        @_apipie_dsl_data = nil
+      end
+
+      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.
+      #
+      #    resource_id "my_own_resource_id"
+      def resource_id(resource_id)
+        Apipie.set_resource_id(@controller, resource_id)
+      end
+
+      def name(name)
+        _apipie_dsl_data[:resource_name] = name
+      end
+
+      def api_base_url(url)
+        _apipie_dsl_data[:api_base_url] = url
+      end
+
+      def short(short)
+        _apipie_dsl_data[:short_description] = short
+      end
+      alias :short_description :short
+
+      def path(path)
+        _apipie_dsl_data[:path] = path
+      end
+
+      def app_info(app_info)
+        _apipie_dsl_data[:app_info] = app_info
+      end
+    end
+
+    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
+        Apipie.set_controller_versions(self, versions)
+      end
+
+    end
+
+    module Common
+      def api_versions(*versions)
+        _apipie_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_dsl_data[:description]
+          raise "Double method description."
+        end
+        _apipie_dsl_data[:description] = description
+      end
+      alias :description :desc
+      alias :full_description :desc
+
+      # Describe available request/response formats
+      #
+      #   formats ['json', 'jsonp', 'xml']
+      def formats(formats) #:doc:
+        return unless Apipie.active_dsl?
+        _apipie_dsl_data[:formats] = formats
+      end
+
+      # 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
+
+      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_presence?
+              description.params.each do |_, param|
+                # check if required parameters are present
+                raise ParamMissing.new(param.name) if param.required && !params.has_key?(param.name)
+              end
+            end
+
+            if Apipie.configuration.validate_value?
+              description.params.each do |_, param|
+                # params validations
+                param.validate(params[:"#{param.name}"]) if params.has_key?(param.name)
+              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
+    # 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
+
+      # 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
+
+      # 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
+
+    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
+      include Apipie::DSL::Resource
+      include Apipie::DSL::Param
+
+      def initialize(controller)
+        @controller = controller
+      end
+
+      def _eval_dsl(&block)
+        instance_eval(&block)
+        return _apipie_dsl_data
+      end
+
+      # 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