apipie-rails 0.3.6 → 0.9.1

data/lib/apipie/dsl_definition.rb

@@ -2,12 +2,20 @@
 
 module Apipie
 
-  # DSL is a module that provides #api, #error, #param, #error.
+  # DSL is a module that provides #api, #error, #param, #returns.
   module DSL
 
     module Base
       attr_reader :apipie_resource_descriptions, :api_params
 
+      def _apipie_eval_dsl(*args, &block)
+        raise 'The Apipie DLS data need to be cleared before evaluating new block' if @_apipie_dsl_data
+        instance_exec(*args, &block)
+        return _apipie_dsl_data
+      ensure
+        _apipie_dsl_data_clear
+      end
+
       private
 
       def _apipie_dsl_data
@@ -24,9 +32,11 @@ module Apipie
          :api_args          => [],
          :api_from_routes   => nil,
          :errors            => [],
+         :tag_list          => [],
+         :returns           => {},
          :params            => [],
          :headers           => [],
-         :resouce_id        => nil,
+         :resource_id       => nil,
          :short_description => nil,
          :description       => nil,
          :examples          => [],
@@ -34,7 +44,8 @@ module Apipie
          :formats           => nil,
          :api_versions      => [],
          :meta              => nil,
-         :show              => true
+         :show              => true,
+         :deprecated        => false
        }
       end
     end
@@ -68,6 +79,11 @@ module Apipie
       def app_info(app_info)
         _apipie_dsl_data[:app_info] = app_info
       end
+
+      def deprecated(value)
+        _apipie_dsl_data[:deprecated] = value
+      end
+
     end
 
     module Action
@@ -123,7 +139,7 @@ module Apipie
       #
       # Example:
       # api :desc => "Show user profile", :path => "/users/", :version => '1.0 - 3.4.2012'
-      # param :id, Fixnum, :desc => "User ID", :required => true
+      # param :id, Integer, :desc => "User ID", :required => true
       # desc <<-EOS
       #   Long description...
       # EOS
@@ -133,10 +149,10 @@ module Apipie
 
         dsl_data = ResourceDescriptionDsl.eval_dsl(self, &block)
         versions = dsl_data[:api_versions]
+        Apipie.set_controller_versions(self, 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
 
@@ -207,6 +223,13 @@ module Apipie
         _apipie_dsl_data[:errors] << [code_or_options, desc, options]
       end
 
+      # Add tags to resources and actions group operations together.
+      def tags(*args)
+        return unless Apipie.active_dsl?
+        tags = args.length == 1 ? args.first : args
+        _apipie_dsl_data[:tag_list] += tags
+      end
+
       def _apipie_define_validators(description)
 
         # [re]define method only if validation is turned on
@@ -237,9 +260,11 @@ module Apipie
               # Only allow params passed in that are defined keys in the api
               # Auto skip the default params (format, controller, action)
               if Apipie.configuration.validate_key?
-                params.reject{|k,_| %w[format controller action].include?(k.to_s) }.each_key do |param|
+                params.reject{|k,_| %w[format controller action].include?(k.to_s) }.each_pair do |param, _|
                   # params allowed
-                  raise UnknownParam.new(param) if method_params.select {|_,p| p.name.to_s == param.to_s}.empty?
+                  if method_params.select {|_,p| p.name.to_s == param.to_s}.empty?
+                    self.class._apipie_handle_validate_key_error params, param
+                  end
                 end
               end
 
@@ -253,7 +278,7 @@ module Apipie
             end
           end
 
-          if (Apipie.configuration.validate == :implicitly || Apipie.configuration.validate == true)
+          if Apipie.configuration.validate == :implicitly || Apipie.configuration.validate == true
             old_method = instance_method(description.method)
 
             define_method(description.method) do |*args|
@@ -267,6 +292,15 @@ module Apipie
         end
       end
 
+      def _apipie_handle_validate_key_error params, param
+        if Apipie.configuration.action_on_non_validated_keys == :raise
+          raise UnknownParam, param
+        elsif Apipie.configuration.action_on_non_validated_keys == :skip
+          params.delete(param)
+          Rails.logger.warn(UnknownParam.new(param).to_s)
+        end
+      end
+
       def _apipie_save_method_params(method, params)
         @method_params ||= {}
         @method_params[method] = params
@@ -295,6 +329,7 @@ module Apipie
       end
     end
 
+
     # this describes the params, it's in separate module because it's
     # used in Validators as well
     module Param
@@ -315,10 +350,17 @@ module Apipie
                                       block]
       end
 
+      def property(param_name, validator, desc_or_options = nil, options = {}, &block) #:doc:
+        return unless Apipie.active_dsl?
+        options[:only_in] ||= :response
+        options[:required] = true if options[:required].nil?
+        param(param_name, validator, desc_or_options, options, &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 =>
+      # when using action_aware params, 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
@@ -340,6 +382,65 @@ module Apipie
         @_current_param_group = nil
       end
 
+      # Describe possible responses
+      #
+      # Example:
+      #     def_param_group :user do
+      #       param :user, Hash do
+      #         param :name, String
+      #       end
+      #     end
+      #
+      #   returns :user, "the speaker"
+      #   returns "the speaker" do
+      #        param_group: :user
+      #   end
+      #   returns :param_group => :user, "the speaker"
+      #   returns :user, :code => 201, :desc => "the created speaker record"
+      #   returns :array_of => :user, "many speakers"
+      #   def hello_world
+      #     render json: {user: {name: "Alfred"}}
+      #   end
+      #
+      def returns(pgroup_or_options, desc_or_options=nil, options={}, &block) #:doc:
+        return unless Apipie.active_dsl?
+
+
+        if desc_or_options.is_a? Hash
+          options.merge!(desc_or_options)
+        elsif !desc_or_options.nil?
+          options[:desc] = desc_or_options
+        end
+
+        if pgroup_or_options.is_a? Hash
+          options.merge!(pgroup_or_options)
+        else
+          options[:param_group] = pgroup_or_options
+        end
+
+        code = options[:code] || 200
+        scope = options[:scope] || _default_param_group_scope
+        descriptor = options[:param_group] || options[:array_of]
+
+        if block.nil?
+          if descriptor.is_a? ResponseDescriptionAdapter
+            adapter = descriptor
+          elsif descriptor.respond_to? :describe_own_properties
+            adapter = ResponseDescriptionAdapter.from_self_describing_class(descriptor)
+          else
+            begin
+              block = Apipie.get_param_group(scope, descriptor) if descriptor
+            rescue
+              raise "No param_group or self-describing class named #{descriptor}"
+            end
+          end
+        elsif descriptor
+          raise "cannot specify both block and param_group"
+        end
+
+        _apipie_dsl_data[:returns][code] = [options, scope, block, adapter]
+      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
@@ -381,13 +482,58 @@ module Apipie
         _apipie_concern_subst.merge!(subst_hash)
       end
 
+      # Allows to update existing params after definition was made (usually needed
+      # when extending the API form plugins).
+      #
+      #     UsersController.apipie_update_params([:create, :update]) do
+      #       param :user, Hash do
+      #         param :oauth, String
+      #       end
+      #      end
+      #
+      # The block is evaluated in scope of the controller. Ohe can pass some additional
+      # objects via additional arguments like this:
+      #
+      #     UsersController.apipie_update_params([:create, :update], [:name, :secret]) do |param_names|
+      #       param :user, Hash do
+      #         param_names.each { |p| param p, String }
+      #       end
+      #      end
+      def _apipie_update_params(method_desc, dsl_data)
+        params_ordered = dsl_data[:params].map do |args|
+          Apipie::ParamDescription.from_dsl_data(method_desc, args)
+        end
+        ParamDescription.merge(method_desc.params_ordered_self, params_ordered)
+      end
+
+      def _apipie_update_meta(method_desc, dsl_data)
+        return unless dsl_data[:meta] && dsl_data[:meta].is_a?(Hash)
+
+        method_desc.metadata ||= {}
+        method_desc.metadata.merge!(dsl_data[:meta])
+      end
+
+      def apipie_update_methods(methods, *args, &block)
+        methods.each do |method|
+          method_desc = Apipie.get_method_description(self, method)
+          unless method_desc
+            raise "Could not find method description for #{self}##{method}. Was the method defined?"
+          end
+          dsl_data = _apipie_eval_dsl(*args, &block)
+          _apipie_update_params(method_desc, dsl_data)
+          _apipie_update_meta(method_desc, dsl_data)
+        end
+      end
+      # backwards compatibility
+      alias_method :apipie_update_params, :apipie_update_methods
+
       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)|
+        _apipie_concern_subst.reduce(string) do |ret, (key, val)|
           ret.gsub(":#{key}", val)
         end
       end
@@ -428,12 +574,19 @@ module Apipie
           description = Apipie.define_method_description(controller, method_name, _apipie_dsl_data)
           controller._apipie_define_validators(description)
         end
+        _apipie_concern_update_api_blocks.each do |(methods, block)|
+          controller.apipie_update_methods(methods, &block)
+        end
       end
 
       def _apipie_concern_data
         @_apipie_concern_data ||= []
       end
 
+      def _apipie_concern_update_api_blocks
+        @_apipie_concern_update_api_blocks ||= []
+      end
+
       def apipie_concern?
         true
       end
@@ -449,6 +602,10 @@ module Apipie
         _apipie_dsl_data_clear
       end
 
+      def update_api(*methods, &block)
+        _apipie_concern_update_api_blocks << [methods, block]
+      end
+
     end
 
     class ResourceDescriptionDsl
@@ -461,14 +618,9 @@ module Apipie
         @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)
+        dsl_data  = self.new(controller)._apipie_eval_dsl(&block)
         if dsl_data[:api_versions].empty?
           dsl_data[:api_versions] = Apipie.controller_versions(controller)
         end

data/lib/apipie/error_description.rb

@@ -1,7 +1,6 @@
 module Apipie
 
   class ErrorDescription
-
     attr_reader :code, :description, :metadata
 
     def self.from_dsl_data(args)
@@ -18,7 +17,15 @@ module Apipie
         @metadata = code_or_options[:meta]
         @description = code_or_options[:desc] || code_or_options[:description]
       else
-        @code = code_or_options
+        @code = 
+          if code_or_options.is_a? Symbol
+            Rack::Utils::SYMBOL_TO_STATUS_CODE[code_or_options]
+          else
+            code_or_options
+          end
+
+        raise UnknownCode, code_or_options unless @code
+
         @metadata = options[:meta]
         @description = desc
       end

data/lib/apipie/errors.rb

@@ -6,6 +6,15 @@ module Apipie
   class ParamError < Error
   end
 
+  class UnknownCode < Error
+  end
+
+  class ReturnsMultipleDefinitionError < Error
+    def to_s
+      "a 'returns' statement cannot indicate both array_of and type"
+    end
+  end
+
   # abstract
   class DefinedParamError < ParamError
     attr_accessor :param
@@ -49,4 +58,29 @@ module Apipie
     end
   end
 
+  class ResponseDoesNotMatchSwaggerSchema < Error
+    def initialize(controller_name, method_name, response_code, error_messages, schema, returned_object)
+      @controller_name = controller_name
+      @method_name = method_name
+      @response_code = response_code
+      @error_messages = error_messages
+      @schema = schema
+      @returned_object = returned_object
+    end
+
+    def to_s
+      "Response does not match swagger schema (#{@controller_name}##{@method_name} #{@response_code}): #{@error_messages}\nSchema: #{JSON(@schema)}\nReturned object: #{@returned_object}"
+    end
+  end
+
+  class NoDocumentedMethod < Error
+    def initialize(controller_name, method_name)
+      @method_name = method_name
+      @controller_name = controller_name
+    end
+
+    def to_s
+      "There is no documented method #{@controller_name}##{@method_name}"
+    end
+  end
 end

data/lib/apipie/extractor/collector.rb

@@ -75,6 +75,10 @@ module Apipie
             if param_desc[:type].first == :number && (key.to_s !~ /id$/ || !Apipie::Validator::NumberValidator.validate(value))
               param_desc[:type].shift
             end
+
+            if param_desc[:type].first == :decimal && (key.to_s !~ /id$/ || !Apipie::Validator::DecimalValidator.validate(value))
+              param_desc[:type].shift
+            end
           end
 
           if value.is_a? Hash

data/lib/apipie/extractor/recorder.rb

@@ -13,12 +13,13 @@ module Apipie
         @query = env["QUERY_STRING"] unless env["QUERY_STRING"].blank?
         @params = Rack::Utils.parse_nested_query(@query)
         @params.merge!(env["action_dispatch.request.request_parameters"] || {})
-        if data = parse_data(env["rack.input"].read)
+        rack_input = env["rack.input"]
+        if data = parse_data(rack_input.read)
           @request_data = data
-          env["rack.input"].rewind
         elsif form_hash = env["rack.request.form_hash"]
           @request_data = reformat_multipart_data(form_hash)
         end
+        rack_input.rewind
       end
 
       def analyse_controller(controller)
@@ -28,7 +29,11 @@ module Apipie
 
       def analyse_response(response)
         if response.last.respond_to?(:body) && data = parse_data(response.last.body)
-          @response_data = data
+          @response_data = if response[1]['Content-Disposition'].to_s.start_with?('attachment')
+                             '<STREAMED ATTACHMENT FILE>'
+                           else
+                             data
+                           end
         end
         @code = response.first
       end
@@ -38,7 +43,7 @@ module Apipie
         @verb = request.request_method.to_sym
         @path = request.path
         @params = request.request_parameters
-        if [:POST, :PUT, :PATCH].include?(@verb)
+        if [:POST, :PUT, :PATCH, :DELETE].include?(@verb)
           @request_data = @params
         else
           @query = request.query_string
@@ -48,9 +53,9 @@ module Apipie
       end
 
       def parse_data(data)
-        return nil if data.to_s =~ /^\s*$/
+        return nil if data.strip.blank?
         JSON.parse(data)
-      rescue StandardError => e
+      rescue StandardError
         data
       end
 
@@ -145,12 +150,8 @@ module Apipie
       end
 
       module FunctionalTestRecording
-        def self.included(base)
-          base.alias_method_chain :process, :api_recording
-        end
-
-        def process_with_api_recording(*args) # action, parameters = nil, session = nil, flash = nil, http_method = 'GET')
-          ret = process_without_api_recording(*args)
+        def process(*) # action, parameters = nil, session = nil, flash = nil, http_method = 'GET')
+          ret = super
           if Apipie.configuration.record
             Apipie::Extractor.call_recorder.analyze_functional_test(self)
             Apipie::Extractor.call_finished
@@ -159,6 +160,7 @@ module Apipie
         ensure
           Apipie::Extractor.clean_call_recorder
         end
+        ruby2_keywords :process if respond_to?(:ruby2_keywords, true)
       end
     end
   end

data/lib/apipie/extractor/writer.rb

@@ -3,11 +3,76 @@ require 'set'
 module Apipie
   module Extractor
     class Writer
+      class << self
+        def compressed
+          Apipie.configuration.compress_examples
+        end
+
+        def update_action_description(controller, action)
+          updater = ActionDescriptionUpdater.new(controller, action)
+          yield updater
+          updater.write!
+        rescue ActionDescriptionUpdater::ControllerNotFound
+          logger.warn("REST_API: Couldn't find controller file for #{controller}")
+        rescue ActionDescriptionUpdater::ActionNotFound
+          logger.warn("REST_API: Couldn't find action #{action} in #{controller}")
+        end
+
+        def write_recorded_examples(examples)
+          FileUtils.mkdir_p(File.dirname(examples_file))
+          content = serialize_examples(examples)
+          content = Zlib::Deflate.deflate(content).force_encoding('utf-8') if compressed
+          File.open(examples_file, 'w') { |f| f << content }
+        end
+
+        def load_recorded_examples
+          return {} unless File.exist?(examples_file)
+          load_json_examples
+        end
+
+        def examples_file
+          pure_path = Rails.root.join(
+            Apipie.configuration.doc_path, 'apipie_examples.json'
+          )
+          zipped_path = pure_path.to_s + '.gz'
+          return zipped_path if compressed
+          pure_path.to_s
+        end
+
+        protected
+
+        def serialize_examples(examples)
+          JSON.pretty_generate(
+            OrderedHash[*examples.sort_by(&:first).flatten(1)]
+          )
+        end
+
+        def deserialize_examples(examples_string)
+          examples = JSON.parse(examples_string)
+          return {} if examples.nil?
+          examples.each_value do |records|
+            records.each do |record|
+              record['verb'] = record['verb'].to_sym if record['verb']
+            end
+          end
+        end
+
+        def load_json_examples
+          raw = IO.read(examples_file)
+          raw = Zlib::Inflate.inflate(raw).force_encoding('utf-8') if compressed
+          deserialize_examples(raw)
+        end
+
+        def logger
+          Extractor.logger
+        end
+      end
 
       def initialize(collector)
         @collector = collector
       end
 
+
       def write_examples
         merged_examples = merge_old_new_examples
         self.class.write_recorded_examples(merged_examples)
@@ -26,47 +91,9 @@ module Apipie
         end
       end
 
-      def self.update_action_description(controller, action)
-        updater = ActionDescriptionUpdater.new(controller, action)
-        yield updater
-        updater.write!
-      rescue ActionDescriptionUpdater::ControllerNotFound
-        logger.warn("REST_API: Couldn't find controller file for #{controller}")
-      rescue ActionDescriptionUpdater::ActionNotFound
-        logger.warn("REST_API: Couldn't find action #{action} in #{controller}")
-      end
-
-      def self.write_recorded_examples(examples)
-        examples_file = self.examples_file
-        FileUtils.mkdir_p(File.dirname(examples_file))
-        File.open(examples_file, "w") do |f|
-          f << JSON.pretty_generate(OrderedHash[*examples.sort_by(&:first).flatten(1)])
-        end
-      end
-
-      def self.load_recorded_examples
-        examples_file = self.examples_file
-        if File.exists?(examples_file)
-          return load_json_examples
-        end
-        return {}
-      end
-
-      def self.examples_file
-        File.join(Rails.root,Apipie.configuration.doc_path,"apipie_examples.json")
-      end
 
       protected
 
-      def self.load_json_examples
-        examples = JSON.load(IO.read(examples_file))
-        return {} if examples.nil?
-        examples.each do |method, records|
-          records.each do |record|
-            record["verb"] = record["verb"].to_sym if record["verb"]
-          end
-        end
-      end
 
       def desc_to_s(description)
         "#{description[:controller].name}##{description[:action]}"
@@ -78,21 +105,26 @@ module Apipie
         %w[title verb path versions query request_data response_data code show_in_doc recorded].each do |k|
           next unless call.has_key?(k)
           ordered_call[k] = case call[k]
-                       when ActiveSupport::HashWithIndifferentAccess
-                         # UploadedFiles break the to_json call, turn them into a string so they don't break
-                         call[k].each do |pkey, pval|
-                           if (pval.is_a?(Rack::Test::UploadedFile) || pval.is_a?(ActionDispatch::Http::UploadedFile))
-                             call[k][pkey] = "<FILE CONTENT '#{pval.original_filename}'>"
-                           end
-                         end
-                         JSON.parse(call[k].to_json) # to_hash doesn't work recursively and I'm too lazy to write the recursion:)
-                       else
-                         call[k]
-                       end
-        end
+                     when ActiveSupport::HashWithIndifferentAccess
+                       convert_file_value(call[k]).to_hash
+                     else
+                       call[k]
+                     end
+      end
         return ordered_call
       end
 
+      def convert_file_value hash
+        hash.each do |k, v|
+          if v.is_a?(Rack::Test::UploadedFile) || v.is_a?(ActionDispatch::Http::UploadedFile)
+            hash[k] = "<FILE CONTENT '#{v.original_filename}'>"
+          elsif v.is_a?(Hash)
+            hash[k] = convert_file_value(v)
+          end
+        end
+        hash
+      end
+
       def load_recorded_examples
         self.class.load_recorded_examples
       end
@@ -131,7 +163,7 @@ module Apipie
             new_example[:title] ||= old_example["title"] if old_example["title"].present?
           end
           new_example
-        end 
+        end
       end
 
       def load_new_examples
@@ -158,7 +190,7 @@ module Apipie
       end
 
       def load_old_examples
-        if File.exists?(@examples_file)
+        if File.exist?(@examples_file)
           if defined? SafeYAML
             return YAML.load_file(@examples_file, :safe=>false)
           else
@@ -172,10 +204,6 @@ module Apipie
         self.class.logger
       end
 
-      def self.logger
-        Extractor.logger
-      end
-
       def showable_in_doc?(call)
         # we don't want to mess documentation with too large examples
         if hash_nodes_count(call["request_data"]) + hash_nodes_count(call["response_data"]) > 100
@@ -267,7 +295,7 @@ module Apipie
       end
 
       def controller_content
-        raise ControllerNotFound.new unless controller_path && File.exists?(controller_path)
+        raise ControllerNotFound.new unless controller_path && File.exist?(controller_path)
         @controller_content ||= File.read(controller_path)
       end
 
@@ -295,7 +323,7 @@ module Apipie
           desc ||= case @action.to_s
                    when "show", "create", "update", "destroy"
                      name = name.singularize
-                     "#{@action.capitalize} #{name =~ /^[aeiou]/ ? "an" : "a"} #{name}"
+                     "#{@action.capitalize} #{name =~ /^[aeiou]/ ? 'an' : 'a'} #{name}"
                    when "index"
                      "List #{name}"
                    end