apipie-rails-jq 1.4.3.pre.beta.pre.jq.1

data/lib/apipie/param_description.rb

@@ -0,0 +1,313 @@
+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, :allow_blank, :validator, :options, :metadata, :show, :as, :validations, :response_only, :request_only
+    attr_reader :additional_properties, :is_array
+    attr_accessor :parent, :required
+
+    alias response_only? response_only
+    alias request_only? request_only
+    alias is_array? is_array
+
+    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 to_s
+      "ParamDescription: #{method_description.id}##{name}"
+    end
+
+    def ==(other)
+      return false unless self.class == other.class
+      if method_description == other.method_description && @options == other.options
+        true
+      else
+        false
+      end
+    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
+      if @options[:param_group]
+        @from_concern = @options[:param_group][:from_concern]
+      end
+
+      if validator.is_a?(Hash)
+        @options.merge!(validator.select{|k,v| k != :array_of })
+      end
+
+      @method_description = method_description
+      @name = concern_subst(name)
+      @as = options[:as] || @name
+      @desc = preformat_text(@options[:desc])
+
+      @parent = @options[:parent]
+      @metadata = @options[:meta]
+
+      @required = is_required?
+
+      @response_only = (@options[:only_in] == :response)
+      @request_only = (@options[:only_in] == :request)
+      raise ArgumentError.new("'#{@options[:only_in]}' is not a valid value for :only_in") if (!@response_only && !@request_only) && @options[:only_in].present?
+
+      @show = if @options.key? :show
+        @options[:show]
+      else
+        true
+      end
+
+      @allow_nil = @options[:allow_nil] || false
+      @allow_blank = @options[:allow_blank] || false
+
+      action_awareness
+
+      if validator
+        if (validator != Hash) && (validator.is_a? Hash) && validator[:array_of]
+          @is_array = true
+          validator = validator[:array_of]
+          raise "an ':array_of =>' validator is allowed exclusively on response-only fields" unless @response_only
+        end
+        @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)) }
+
+      @additional_properties = @options[:additional_properties]
+      @deprecated = @options[:deprecated] || false
+    end
+
+    def from_concern?
+      method_description.from_concern? || @from_concern
+    end
+
+    def normalized_value(value)
+      if value.is_a?(ActionController::Parameters) && !value.is_a?(Hash)
+        value.to_unsafe_hash
+      elsif value.is_a? Array
+        value.map { |v| normalized_value (v) }
+      else
+        value
+      end
+    end
+
+    def validate(value)
+      return true if allow_nil && value.nil?
+      return true if allow_blank && value.blank?
+      value = normalized_value(value)
+      if (!allow_nil && value.nil?) || (blank_forbidden? && value.blank?) || !validator.valid?(value)
+        error = validator.error
+        error = ParamError.new(error) unless error.is_a? StandardError
+        raise error
+      end
+    end
+
+    def blank_forbidden?
+      !Apipie.configuration.ignore_allow_blank_false && !allow_blank && !validator.ignore_allow_blank?
+    end
+
+    def process_value(value)
+      value = normalized_value(value)
+      if @validator.respond_to?(:process_value)
+        @validator.process_value(value)
+      else
+        value
+      end
+    end
+
+    def full_name
+      name_parts = parents_and_self.map{|p| p.name if p.show}.compact
+      return name.to_s if name_parts.blank?
+      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(lang = nil)
+      hash = {
+        name: name.to_s,
+        full_name: full_name,
+        description: preformat_text(Apipie.app.translate(@options[:desc], lang)),
+        required: required,
+        allow_nil: allow_nil,
+        allow_blank: allow_blank,
+        validator: validator.to_s,
+        expected_type: validator.expected_type,
+        metadata: metadata,
+        show: show,
+        validations: validations,
+        deprecated: deprecated?
+      }
+
+      if deprecation.present?
+        hash[:deprecation] = deprecation.to_json
+      end
+
+      if sub_params = validator.params_ordered
+        hash[:params] = sub_params.map { |p| p.to_json(lang)}
+      end
+      hash
+    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 descriptions. 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
+
+    def self.merge(target_params, source_params)
+      params_to_merge, params_to_add = source_params.partition do |source_param|
+        target_params.any? { |target_param| source_param.name == target_param.name }
+      end
+      unify(target_params + params_to_merge)
+      target_params.concat(params_to_add)
+    end
+
+    # action awareness is being inherited from ancestors (in terms of
+    # nested params)
+    def action_aware?
+      if @options.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
+    # create/update actions.
+    def action_awareness
+      if action_aware?
+        if !@options.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 !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 preformat_text(text)
+      concern_subst(Apipie.markup_to_html(text || ''))
+    end
+
+    def is_required?
+      if @options.key?(:required)
+        if (@options[:required] == true) || (@options[:required] == false)
+          @options[:required]
+        else
+          Array(@options[:required]).include?(@method_description.method.to_sym)
+        end
+      else
+        Apipie.configuration.required_by_default?
+      end
+    end
+
+    def deprecated?
+      @deprecated.present?
+    end
+
+    def deprecation
+      return if @deprecated.blank? || @deprecated == true
+
+      case @deprecated
+      when Hash
+        Apipie::ParamDescription::Deprecation.new(
+          info: @deprecated[:info],
+          deprecated_in: @deprecated[:in],
+          sunset_at: @deprecated[:sunset]
+        )
+      when String
+        Apipie::ParamDescription::Deprecation.new(info: @deprecated)
+      end
+    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,152 @@
+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 - resource name
+  # formats - acceptable request/response format types
+  # headers - array of headers
+  # deprecated - boolean indicating if resource is deprecated
+  class ResourceDescription
+
+    attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
+      :_path, :_params_args, :_returns_args, :_tag_list_arg, :_errors_args,
+      :_formats, :_parent, :_metadata, :_headers, :_deprecated
+
+    def initialize(controller, id, dsl_data = nil, version = nil)
+      @_methods = ActiveSupport::OrderedHash.new
+      @_params_args = []
+      @_errors_args = []
+      @_returns_args = []
+
+      @controller = controller
+      @_id = id
+      @_version = version || Apipie.configuration.default_version
+      @_parent = Apipie.value_from_parents(controller.superclass, version) do |parent, ver|
+        Apipie.get_resource_description(parent, ver)
+      end
+
+      update_from_dsl_data(dsl_data) if dsl_data
+    end
+
+    def update_from_dsl_data(dsl_data)
+      @_resource_name = dsl_data[:resource_name] if dsl_data[:resource_name]
+      @_full_description = 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]
+      @_returns_args = dsl_data[:returns]
+      @_tag_list_arg = dsl_data[:tag_list]
+      @_metadata = dsl_data[:meta]
+      @_api_base_url = dsl_data[:api_base_url]
+      @_headers = dsl_data[:headers]
+      @_deprecated = dsl_data[:deprecated] || false
+
+      if dsl_data[:app_info]
+        Apipie.configuration.app_info[_version] = dsl_data[:app_info]
+      end
+    end
+
+    def _version
+      @_version || @_parent.try(:_version) || Apipie.configuration.default_version
+    end
+
+    def _api_base_url
+      @_api_base_url || @_parent.try(:_api_base_url) || Apipie.api_base_url(_version)
+    end
+
+    def name
+      @name ||= case resource_name
+                when Proc
+          resource_name.call(controller)
+                when Symbol
+          controller.public_send(resource_name)
+                when String
+          resource_name
+        else
+          default_name
+        end
+    end
+    alias _name name
+
+    def add_method_description(method_description)
+      Apipie.debug "@resource_descriptions[#{self._version}][#{self._id}]._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.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 valid_method_name?(method_name)
+      @_methods.keys.map(&:to_s).include?(method_name.to_s)
+    end
+
+    def to_json(method_name = nil, lang = nil)
+      if method_name && !valid_method_name?(method_name)
+        raise "Method #{method_name} not found for resource #{_name}"
+      end
+
+      methods = if method_name.blank?
+        @_methods.collect { |key, method_description| method_description.to_json(lang) }
+      else
+        [@_methods[method_name.to_sym].to_json(lang)]
+      end
+
+      {
+        :doc_url => doc_url,
+        :id => _id,
+        :api_url => api_url,
+        :name => name,
+        :short_description => Apipie.app.translate(@_short_description, lang),
+        :full_description => Apipie.markup_to_html(Apipie.app.translate(@_full_description, lang)),
+        :version => _version,
+        :formats => @_formats,
+        :metadata => @_metadata,
+        :methods => methods,
+        :headers => _headers,
+        :deprecated => @_deprecated
+      }
+    end
+
+    protected
+
+    def resource_name
+      @_resource_name.presence || @_parent&.resource_name
+    end
+
+    private
+
+    def default_name
+      @_id.split('-').map(&:capitalize).join('::')
+    end
+
+  end
+end

data/lib/apipie/response_description.rb

@@ -0,0 +1,157 @@
+module Apipie
+
+  class ResponseDescription
+    class ResponseObject
+      include Apipie::DSL::Base
+      include Apipie::DSL::Param
+
+      attr_accessor :additional_properties, :typename
+      attr_reader :headers
+
+      def initialize(method_description, scope, block, typename)
+        @method_description = method_description
+        @scope = scope
+        @param_group = {scope: scope}
+        @additional_properties = false
+        @typename = typename
+        @headers = []
+
+        self.instance_exec(&block) if block
+
+        prepare_hash_params
+      end
+
+      # this routine overrides Param#_default_param_group_scope and is called if Param#param_group is
+      # invoked during the instance_exec call in ResponseObject#initialize
+      def _default_param_group_scope
+        @scope
+      end
+
+      def name
+        "response #{@code} for #{@method_description.method}"
+      end
+
+      def params_ordered
+        @params_ordered ||= _apipie_dsl_data[:params].map do |args|
+          options = args.find { |arg| arg.is_a? Hash }
+          options[:param_group] = @param_group
+          Apipie::ParamDescription.from_dsl_data(@method_description, args) unless options[:only_in] == :request
+        end.compact
+      end
+
+      def prepare_hash_params
+        @hash_params = params_ordered.reduce({}) do |h, param|
+          h.update(param.name.to_sym => param)
+        end
+      end
+
+      # @param [String] header_name
+      # @param [String, symbol, Class] validator
+      # @param [String] description
+      # @param [Hash] options
+      def header(header_name, validator, description, options = {})
+        @headers << {
+          name: header_name,
+          validator: validator.to_s.downcase,
+          description: description,
+          options: options
+        }
+      end
+    end
+  end
+
+
+  class ResponseDescription
+    include Apipie::DSL::Base
+    include Apipie::DSL::Param
+
+    attr_reader :code, :description, :scope, :type_ref, :hash_validator, :is_array_of
+
+    def self.from_dsl_data(method_description, code, args)
+      options, scope, block, adapter = args
+
+      Apipie::ResponseDescription.new(method_description,
+                                      code,
+                                      options,
+                                      scope,
+                                      block,
+                                      adapter)
+    end
+
+    def initialize(method_description, code, options, scope, block, adapter)
+
+      @type_ref = options[:param_group]
+      @is_array_of = options[:array_of] || false
+      raise ReturnsMultipleDefinitionError, options if @is_array_of && @type_ref
+
+      @type_ref ||= @is_array_of
+
+      @method_description = method_description
+
+      @code =
+        if code.is_a? Symbol
+          begin
+            Rack::Utils.status_code(code)
+          rescue ArgumentError
+            nil
+          end
+        else
+          code
+        end
+
+      @description = options[:desc]
+      if @description.nil?
+        @description = Rack::Utils::HTTP_STATUS_CODES[@code]
+        raise "Cannot infer description from status code #{@code}" if @description.nil?
+      end
+      @scope = scope
+
+      if adapter
+        @response_object = adapter
+      else
+        @response_object = ResponseObject.new(method_description, scope, block, @type_ref)
+      end
+
+      @response_object.additional_properties ||= options[:additional_properties]
+    end
+
+    def is_array?
+      @is_array_of != false
+    end
+
+    delegate :typename, to: :@response_object
+
+    def param_description
+      nil
+    end
+
+    delegate :params_ordered, to: :@response_object
+
+    def additional_properties
+      !!@response_object.additional_properties
+    end
+    alias allow_additional_properties additional_properties
+
+    # @return [Array<Hash>]
+    def headers
+      # TODO: Support headers for Apipie::ResponseDescriptionAdapter
+      if @response_object.is_a?(Apipie::ResponseDescriptionAdapter)
+        return []
+      end
+
+      @response_object.headers
+    end
+
+    # @return [Hash{Symbol->TrueClass | FalseClass}]
+    def to_json(lang = nil)
+      {
+          :code => code,
+          :description => Apipie.app.translate(description, lang),
+          :is_array => is_array?,
+          :returns_object => params_ordered.map{ |param| param.to_json(lang).tap{|h| h.delete(:validations) }}.flatten,
+          :additional_properties => additional_properties,
+          :headers => headers
+      }
+    end
+  end
+end