jmoses_apipie-rails 0.0.23

data/lib/apipie/method_description.rb

@@ -0,0 +1,191 @@
+require 'set'
+module Apipie
+
+  class MethodDescription
+
+    class Api
+
+      attr_accessor :short_description, :path, :http_method
+
+      def initialize(method, path, desc)
+        @http_method = method.to_s
+        @path = path
+        @short_description = desc
+      end
+
+    end
+
+    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats
+
+    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, concern_subst(path), concern_subst(desc))
+      end
+
+      desc = dsl_data[:description] || ''
+      @full_description = Apipie.markup_to_html(desc)
+
+      @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
+
+      @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
+      "#{resource._id}##{method}"
+    end
+
+    def params
+      params_ordered.reduce(ActiveSupport::OrderedHash.new) { |h,p| h[p.name] = p; h }
+    end
+
+    def params_ordered
+      all_params = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # 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)
+      all_params.find_all(&:validator)
+    end
+
+    def errors
+      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.find_all do |err|
+          !@errors.any? { |e| e.code == err.code }
+        end
+      end
+      @merged_errors.concat(@errors)
+      return @merged_errors
+    end
+
+    def version
+      resource._version
+    end
+
+    def doc_url
+      crumbs = []
+      crumbs << @resource._version if Apipie.configuration.version_in_url
+      crumbs << @resource._id
+      crumbs << @method
+      Apipie.full_url crumbs.join('/')
+    end
+
+    def create_api_url(api)
+      path = "#{Apipie.api_base_url(@resource._version)}#{api.path}"
+      path = path[0..-2] if path[-1..-1] == '/'
+      return path
+    end
+
+    def method_apis_to_json
+      @apis.each.collect do |api|
+        {
+          :api_url => create_api_url(api),
+          :http_method => api.http_method.to_s,
+          :short_description => api.short_description
+        }
+      end
+    end
+
+    def see
+      @see
+    end
+
+    def formats
+      @formats || @resource._formats
+    end
+
+    def to_json
+      {
+        :doc_url => doc_url,
+        :name => @method,
+        :apis => method_apis_to_json,
+        :formats => formats,
+        :full_description => @full_description,
+        :errors => errors.map(&:to_json),
+        :params => params_ordered.map(&:to_json).flatten,
+        :examples => @examples,
+        :see => see.map(&:to_json)
+      }
+    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)
+      new_param_names = Set.new(new_params.map(&:name))
+      params.delete_if { |p| new_param_names.include?(p.name) }
+      params.concat(new_params)
+    end
+
+    def load_recorded_examples
+      (Apipie.recorded_examples[id] || []).
+        find_all { |ex| ex["show_in_doc"].to_i > 0 }.
+        find_all { |ex| ex["versions"].nil? || ex["versions"].include?(self.version) }.
+        sort_by { |ex| ex["show_in_doc"] }.
+        map { |ex| format_example(ex.symbolize_keys) }
+    end
+
+    def format_example_data(data)
+      case data
+      when Array, Hash
+        JSON.pretty_generate(data).gsub(/: \[\s*\]/,": []").gsub(/\{\s*\}/,"{}")
+      else
+        data
+      end
+    end
+
+    def format_example(ex)
+      example = "#{ex[:verb]} #{ex[:path]}"
+      example << "?#{ex[:query]}" unless ex[:query].blank?
+      example << "\n" << format_example_data(ex[:request_data]).to_s if ex[:request_data]
+      example << "\n" << ex[:code].to_s
+      example << "\n" << format_example_data(ex[:response_data]).to_s if ex[:response_data]
+      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

@@ -0,0 +1,204 @@
+module Apipie
+
+  # method parameter description
+  #
+  # name - method name (show)
+  # desc - description
+  # required - boolean if required
+  # validator - Validator::BaseValidator subclass
+  class ParamDescription
+
+    attr_reader :method_description, :name, :desc, :allow_nil, :validator, :options, :validations
+
+    attr_accessor :parent, :required
+
+    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 = options.merge(desc_or_options)
+      elsif desc_or_options.is_a?(String)
+        options[:desc] = desc_or_options
+      elsif !desc_or_options.nil?
+        raise ArgumentError.new("param description: expected description or options as 3rd parameter")
+      end
+
+      options.symbolize_keys!
+
+      # we save options to know what was passed in DSL
+      @options = options
+
+      @method_description = method_description
+      @name = concern_subst(name)
+      @desc = concern_subst(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
+
+      action_awareness
+
+      if validator
+        @validator = Validator::BaseValidator.find(self, validator, @options, block)
+        raise "Validator for #{validator} not found." unless @validator
+      end
+
+      @validations = Array(options[:validations]).map {|v| concern_subst(Apipie.markup_to_html(v)) }
+    end
+
+    def validate(value)
+      return true if @allow_nil && value.nil?
+      unless @validator.valid?(value)
+        error = @validator.error
+        error = ParamError.new(error) unless error.is_a? Exception
+        raise error
+      end
+    end
+
+    def full_name
+      name_parts = parents_and_self.map(&:name)
+      return ([name_parts.first] + name_parts[1..-1].map { |n| "[#{n}]" }).join("")
+    end
+
+    # returns an array of all the parents: starting with the root parent
+    # ending with itself
+    def parents_and_self
+      ret = []
+      if self.parent
+        ret.concat(self.parent.parents_and_self)
+      end
+      ret << self
+      ret
+    end
+
+    def to_json
+      if validator.is_a? Apipie::Validator::HashValidator
+        {
+          :name => name.to_s,
+          :anchor => anchor,
+          :full_name => full_name,
+          :description => desc,
+          :required => required,
+          :allow_nil => allow_nil,
+          :validator => validator.to_s,
+          :expected_type => validator.expected_type,
+          :params => validator.hash_params_ordered.map(&:to_json),
+          :validations => validations
+        }
+      else
+        {
+          :name => name.to_s,
+          :anchor => anchor,
+          :full_name => full_name,
+          :description => desc,
+          :required => required,
+          :allow_nil => allow_nil,
+          :validator => validator.to_s,
+          :expected_type => validator.expected_type,
+          :validations => validations
+        }
+      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
+
+    def concern_subst(string)
+      return string if string.nil? or !method_description.from_concern?
+
+      original = string
+      string = ":#{original}" if original.is_a? Symbol
+
+      replaced = method_description.resource.controller._apipie_perform_concern_subst(string)
+
+      return original if replaced == string
+      return replaced.to_sym if original.is_a? Symbol
+      return replaced
+    end
+
+    def anchor
+      (full_name.to_s || "").gsub(/\W/, '_').gsub(/_$/, '')
+    end
+  end
+
+end

data/lib/apipie/railtie.rb

@@ -0,0 +1,9 @@
+module Apipie
+  class Railtie < Rails::Railtie
+    initializer 'apipie.controller_additions' do
+      ActiveSupport.on_load :action_controller do
+        extend Apipie::DSL::Controller
+      end
+    end
+  end
+end

data/lib/apipie/resource_description.rb

@@ -0,0 +1,102 @@
+module Apipie
+
+  # Resource description
+  #
+  # version - api version (1)
+  # description
+  # path - relative path (/api/articles)
+  # methods - array of keys to Apipie.method_descriptions (array of Apipie::MethodDescription)
+  # name - human readable alias of resource (Articles)
+  # id - resouce name
+  # formats - acceptable request/response format types
+  class ResourceDescription
+
+    attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
+      :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent
+
+    def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
+
+      @_methods = ActiveSupport::OrderedHash.new
+      @_params_args = []
+      @_errors_args = []
+
+      @controller = controller
+      @_id = resource_name
+      @_version = version || Apipie.configuration.default_version
+      @_name = @_id.humanize
+      @_parent = Apipie.get_resource_description(controller.superclass, version)
+
+      update_from_dsl_data(dsl_data) if dsl_data
+    end
+
+    def update_from_dsl_data(dsl_data)
+      @_name = dsl_data[:resource_name] if dsl_data[:resource_name]
+      @_full_description = Apipie.markup_to_html(dsl_data[:description])
+      @_short_description = dsl_data[:short_description]
+      @_path = dsl_data[:path] || ""
+      @_formats = dsl_data[:formats]
+      @_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
+      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 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
+    end
+
+    def method_description(method_name)
+      @_methods[method_name.to_sym]
+    end
+
+    def remove_method_description(method_name)
+      if @_methods.has_key?(method_name)
+        @_methods.delete(method_name)
+      end
+    end
+
+    def method_descriptions
+      @_methods.values
+    end
+
+    def doc_url
+      crumbs = []
+      crumbs << _version if Apipie.configuration.version_in_url
+      crumbs << @_id
+      Apipie.full_url crumbs.join('/')
+    end
+
+    def api_url; "#{Apipie.api_base_url(_version)}#{@_path}"; end
+
+    def to_json(method_name = nil)
+
+      methods = if method_name.blank?
+        @_methods.collect { |key, method_description| method_description.to_json}
+      else
+        [@_methods[method_name.to_sym].to_json]
+      end
+
+      {
+        :doc_url => doc_url,
+        :api_url => api_url,
+        :name => @_name,
+        :short_description => @_short_description,
+        :full_description => @_full_description,
+        :version => _version,
+        :formats => @_formats,
+        :methods => methods
+      }
+    end
+
+  end
+end