apipierails3 0.0.1

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,124 @@
+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
+  # 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, :_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
+      @_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]
+      @_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 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 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.app.translate(@_full_description, lang),
+        :version => _version,
+        :formats => @_formats,
+        :metadata => @_metadata,
+        :methods => methods,
+        :headers => _headers,
+        :deprecated => @_deprecated
+      }
+    end
+
+  end
+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