apipie-rails 0.3.6 → 0.5.17

data/lib/apipie/method_description.rb

@@ -5,7 +5,7 @@ module Apipie
 
     class Api
 
-      attr_accessor :short_description, :path, :http_method, :from_routes, :options
+      attr_accessor :short_description, :path, :http_method, :from_routes, :options, :returns
 
       def initialize(method, path, desc, options)
         @http_method = method.to_s
@@ -17,7 +17,8 @@ module Apipie
 
     end
 
-    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :metadata, :headers, :show
+    attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :headers, :show
+    attr_accessor :metadata
 
     def initialize(method, resource, dsl_data)
       @method = method.to_s
@@ -34,6 +35,12 @@ module Apipie
         Apipie::ErrorDescription.from_dsl_data(args)
       end
 
+      @tag_list = dsl_data[:tag_list]
+
+      @returns = dsl_data[:returns].map do |code,args|
+        Apipie::ResponseDescription.from_dsl_data(self, code, args)
+      end
+
       @see = dsl_data[:see].map do |args|
         Apipie::SeeDescription.new(args)
       end
@@ -46,7 +53,8 @@ module Apipie
 
       @params_ordered = dsl_data[:params].map do |args|
         Apipie::ParamDescription.from_dsl_data(self, args)
-      end
+      end.reject{|p| p.response_only? }
+
       @params_ordered = ParamDescription.unify(@params_ordered)
       @headers = dsl_data[:headers]
 
@@ -65,6 +73,10 @@ module Apipie
       params_ordered.reduce(ActiveSupport::OrderedHash.new) { |h,p| h[p.name] = p; h }
     end
 
+    def params_ordered_self
+      @params_ordered
+    end
+
     def params_ordered
       all_params = []
       parent = Apipie.get_resource_description(@resource.controller.superclass)
@@ -81,6 +93,34 @@ module Apipie
       all_params.find_all(&:validator)
     end
 
+    def returns_self
+      @returns
+    end
+
+    def tag_list
+      all_tag_list = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get tags from parent resource description
+      parent_tags = [parent, @resource].compact.flat_map { |resource| resource._tag_list_arg }
+      Apipie::TagListDescription.new((parent_tags + @tag_list).uniq.compact)
+    end
+
+    def returns
+      all_returns = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get response descriptions from parent resource description
+      [parent, @resource].compact.each do |resource|
+        resource_returns = resource._returns_args.map do |code, args|
+          Apipie::ResponseDescription.from_dsl_data(self, code, args)
+        end
+        merge_returns(all_returns, resource_returns)
+      end
+
+      merge_returns(all_returns, @returns)
+    end
+
     def errors
       return @merged_errors if @merged_errors
       @merged_errors = []
@@ -125,7 +165,7 @@ module Apipie
           :api_url => create_api_url(api),
           :http_method => api.http_method.to_s,
           :short_description => Apipie.app.translate(api.short_description, lang),
-          :deprecated => api.options[:deprecated]
+          :deprecated => resource._deprecated || api.options[:deprecated]
         }
       end
     end
@@ -147,6 +187,7 @@ module Apipie
         :full_description => Apipie.app.translate(@full_description, lang),
         :errors => errors.map(&:to_json),
         :params => params_ordered.map{ |param| param.to_json(lang) }.flatten,
+        :returns => @returns.map{ |return_item| return_item.to_json(lang) }.flatten,
         :examples => @examples,
         :metadata => @metadata,
         :see => see.map(&:to_json),
@@ -185,6 +226,12 @@ module Apipie
       params.concat(new_params)
     end
 
+    def merge_returns(returns, new_returns)
+      new_return_codes = Set.new(new_returns.map(&:code))
+      returns.delete_if { |p| new_return_codes.include?(p.code) }
+      returns.concat(new_returns)
+    end
+
     def load_recorded_examples
       (Apipie.recorded_examples[id] || []).
         find_all { |ex| ex["show_in_doc"].to_i > 0 }.

data/lib/apipie/param_description.rb

@@ -8,9 +8,14 @@ module Apipie
   # validator - Validator::BaseValidator subclass
   class ParamDescription
 
-    attr_reader :method_description, :name, :desc, :allow_nil, :validator, :options, :metadata, :show, :as, :validations
+    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_method :response_only?, :response_only
+    alias_method :request_only?, :request_only
+    alias_method :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,
@@ -21,6 +26,19 @@ module Apipie
                                    &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)
@@ -49,6 +67,10 @@ module Apipie
 
       @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.has_key? :show
         @options[:show]
       else
@@ -56,23 +78,45 @@ module Apipie
       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
+          rest_of_options = validator
+          validator = validator[:array_of]
+          options.merge!(rest_of_options.select{|k,v| k != :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]
     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?) || !@validator.valid?(value)
         error = @validator.error
         error = ParamError.new(error) unless error.is_a? StandardError
@@ -81,6 +125,7 @@ module Apipie
     end
 
     def process_value(value)
+      value = normalized_value(value)
       if @validator.respond_to?(:process_value)
         @validator.process_value(value)
       else
@@ -111,6 +156,7 @@ module Apipie
                :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,
@@ -131,7 +177,7 @@ module Apipie
       self
     end
 
-    # merge param descripsiont. Allows defining hash params on more places
+    # merge param descriptions. Allows defining hash params on more places
     # (e.g. in param_groups). For example:
     #
     #     def_param_group :user do
@@ -151,6 +197,14 @@ module Apipie
       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?

data/lib/apipie/resource_description.rb

@@ -10,17 +10,19 @@ module Apipie
   # id - resouce 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, :_name, :_params_args, :_errors_args, :_formats, :_parent, :_metadata,
-      :_headers
+      :_path, :_name, :_params_args, :_returns_args, :_tag_list_arg, :_errors_args,
+      :_formats, :_parent, :_metadata, :_headers, :_deprecated
 
     def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
 
       @_methods = ActiveSupport::OrderedHash.new
       @_params_args = []
       @_errors_args = []
+      @_returns_args = []
 
       @controller = controller
       @_id = resource_name
@@ -39,9 +41,12 @@ module Apipie
       @_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]
@@ -101,6 +106,7 @@ module Apipie
 
       {
         :doc_url => doc_url,
+        :id => _id,
         :api_url => api_url,
         :name => @_name,
         :short_description => Apipie.app.translate(@_short_description, lang),
@@ -109,7 +115,8 @@ module Apipie
         :formats => @_formats,
         :metadata => @_metadata,
         :methods => methods,
-        :headers => _headers
+        :headers => _headers,
+        :deprecated => @_deprecated
       }
     end
 

data/lib/apipie/response_description.rb

@@ -0,0 +1,131 @@
+module Apipie
+
+  class ResponseDescription
+    class ResponseObject
+      include Apipie::DSL::Base
+      include Apipie::DSL::Param
+
+      attr_accessor :additional_properties, :typename
+
+      def initialize(method_description, scope, block, typename)
+        @method_description = method_description
+        @scope = scope
+        @param_group = {scope: scope}
+        @additional_properties = false
+        @typename = typename
+
+        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
+
+    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 is_array?
+      @is_array_of != false
+    end
+
+    def typename
+      @response_object.typename
+    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
+
+      if code.is_a? Symbol
+        @code = Rack::Utils::SYMBOL_TO_STATUS_CODE[code]
+      else
+        @code = 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 param_description
+      nil
+    end
+
+    def params_ordered
+      @response_object.params_ordered
+    end
+
+    def additional_properties
+      !!@response_object.additional_properties
+    end
+    alias :allow_additional_properties :additional_properties
+
+    def to_json(lang=nil)
+      {
+          :code => code,
+          :description => description,
+          :is_array => is_array?,
+          :returns_object => params_ordered.map{ |param| param.to_json(lang).tap{|h| h.delete(:validations) }}.flatten,
+          :additional_properties => additional_properties,
+      }
+    end
+  end
+end

data/lib/apipie/response_description_adapter.rb

@@ -0,0 +1,200 @@
+module Apipie
+
+  def self.prop(name, expected_type, options={}, sub_properties=[])
+    Apipie::ResponseDescriptionAdapter::PropDesc.new(name, expected_type, options, sub_properties)
+  end
+
+  def self.additional_properties(yesno)
+    Apipie::ResponseDescriptionAdapter::AdditionalPropertiesModifier.new(yesno)
+  end
+
+  class ResponseDescriptionAdapter
+    class Modifier
+      def apply(adapter)
+        raise "Modifer subclass must implement 'apply' method"
+      end
+    end
+
+    class AdditionalPropertiesModifier < Modifier
+      def initialize(additional_properties_allowed)
+        @additional_properties_allowed = additional_properties_allowed
+      end
+
+      def apply(adapter)
+        adapter.additional_properties =  @additional_properties_allowed
+      end
+    end
+  end
+
+
+  class ResponseDescriptionAdapter
+
+    #
+    # A ResponseDescriptionAdapter::PropDesc object pretends to be an Apipie::Param in a ResponseDescription
+    #
+    # To successfully masquerade as such, it needs to:
+    #    respond_to?('name') and/or ['name'] returning the name of the parameter
+    #    respond_to?('required') and/or ['required'] returning boolean
+    #    respond_to?('additional_properties') and/or ['additional_properties'] returning boolean
+    #    respond_to?('validator') and/or ['validator'] returning 'nil' (so type is 'string'), or an object that:
+    #           1) describes a type.  currently type is inferred as follows:
+    #                 if validator.is_a? Apipie::Validator::EnumValidator -->  respond_to? 'values' (returns array).  Type is enum or boolean
+    #                 else: use v.expected_type().  This is expected to be the swagger type, or:
+    #                     numeric ==> swagger type is 'number'
+    #                     hash ==> swagger type is 'object' and validator should respond_to? 'params_ordered'
+    #                     array ==> swagger type is array and validator (FUTURE) should indicate type of element
+
+    class PropDesc
+
+      def to_s
+        "PropDesc -- name: #{@name}  type: #{@expected_type} required: #{@required} options: #{@options} subprop count: #{@sub_properties.length} additional properties: #{@additional_properties}"
+      end
+
+      #
+      # a ResponseDescriptionAdapter::PropDesc::Validator pretends to be an Apipie::Validator
+      #
+      class Validator
+        attr_reader :expected_type
+
+        def [](key)
+          return self.send(key) if self.respond_to?(key.to_s)
+        end
+
+        def initialize(expected_type, enum_values=nil, sub_properties=nil)
+          @expected_type = expected_type
+          @enum_values = enum_values
+          @is_enum = !!enum_values
+          @sub_properties = sub_properties
+        end
+
+        def is_enum?
+          !!@is_enum
+        end
+
+        def values
+          @enum_values
+        end
+
+        def params_ordered
+          raise "Only validators with expected_type 'object' can have sub-properties" unless @expected_type == 'object'
+          @sub_properties
+        end
+      end
+
+      #======================================================================
+
+
+      def initialize(name, expected_type, options={}, sub_properties=[])
+        @name = name
+        @required = true
+        @required = false if options[:required] == false
+        @expected_type = expected_type
+        @additional_properties = false
+
+        options[:desc] ||= options[:description]
+        @description = options[:desc]
+        @options = options
+        @is_array = options[:is_array] || false
+        @sub_properties = []
+        for prop in sub_properties do
+          add_sub_property(prop)
+        end
+      end
+
+      def [](key)
+        return self.send(key) if self.respond_to?(key.to_s)
+      end
+
+      def add_sub_property(prop_desc)
+        raise "Only properties with expected_type 'object' can have sub-properties" unless @expected_type == 'object'
+        if prop_desc.is_a? PropDesc
+          @sub_properties << prop_desc
+        elsif prop_desc.is_a? Modifier
+          prop_desc.apply(self)
+        else
+          raise "Unrecognized prop_desc type (#{prop_desc.class})"
+        end
+      end
+
+      def to_json(lang)
+        {
+            name: name,
+            required: required,
+            validator: validator,
+            description: description,
+            additional_properties: additional_properties,
+            is_array: is_array?,
+            options: options
+        }
+      end
+      attr_reader :name, :required, :expected_type, :options, :description
+      attr_accessor :additional_properties
+
+      alias_method :desc, :description
+
+      def is_array?
+        @is_array
+      end
+
+      def validator
+        Validator.new(@expected_type, options[:values], @sub_properties)
+      end
+    end
+  end
+
+  #======================================================================
+
+  class ResponseDescriptionAdapter
+
+    def self.from_self_describing_class(cls)
+      adapter = ResponseDescriptionAdapter.new(cls.to_s)
+      props = cls.describe_own_properties
+      adapter.add_property_descriptions(props)
+      adapter
+    end
+
+    def initialize(typename)
+      @property_descs = []
+      @additional_properties = false
+      @typename = typename
+    end
+
+    attr_accessor :additional_properties, :typename
+
+    def allow_additional_properties
+      additional_properties
+    end
+
+    def to_json
+      params_ordered.to_json
+    end
+
+    def add(prop_desc)
+      if prop_desc.is_a? PropDesc
+        @property_descs << prop_desc
+      elsif prop_desc.is_a? Modifier
+        prop_desc.apply(self)
+      else
+        raise "Unrecognized prop_desc type (#{prop_desc.class})"
+      end
+    end
+
+    def add_property_descriptions(prop_descs)
+      for prop_desc in prop_descs
+        add(prop_desc)
+      end
+    end
+
+    def property(name, expected_type, options)
+      @property_descs << PropDesc.new(name, expected_type, options)
+    end
+
+    def params_ordered
+      @property_descs
+    end
+
+    def is_array?
+      false
+    end
+  end
+end

data/lib/apipie/routes_formatter.rb

@@ -16,7 +16,7 @@ module Apipie
     end
 
     def format_path(rails_route)
-      rails_route.path.spec.to_s.gsub('(.:format)', '')
+      File.join(rails_route.base_url, rails_route.path.spec.to_s.gsub('(.:format)', ''))
     end
 
     def format_verb(rails_route)