apipie-rails 0.5.7 → 0.5.8

data/lib/apipie-rails.rb

@@ -12,6 +12,8 @@ require "apipie/resource_description"
 require "apipie/param_description"
 require "apipie/errors"
 require "apipie/error_description"
+require "apipie/response_description"
+require "apipie/response_description_adapter"
 require "apipie/see_description"
 require "apipie/validator"
 require "apipie/railtie"

data/lib/apipie/application.rb

@@ -55,7 +55,7 @@ module Apipie
     # this method does in depth search for the route controller
     def route_app_controller(app, route, visited_apps = [])
       if route.defaults[:controller]
-        controller_name = (route.defaults[:controller] + 'Controller').camelize
+        controller_name = "#{route.defaults[:controller]}_controller".camelize
         controller_name.safe_constantize
       end
     end

data/lib/apipie/configuration.rb

@@ -1,7 +1,8 @@
 module Apipie
   class Configuration
 
-    attr_accessor :app_name, :app_info, :copyright, :markup, :disqus_shortname,
+    attr_accessor :app_name, :app_info, :copyright, :compress_examples,
+      :markup, :disqus_shortname,
       :api_base_url, :doc_base_url, :required_by_default, :layout,
       :default_version, :debug, :version_in_url, :namespaced_resources,
       :validate, :validate_value, :validate_presence, :validate_key, :authenticate, :doc_path,
@@ -9,7 +10,8 @@ module Apipie
       :link_extension, :record, :languages, :translate, :locale, :default_locale,
       :persist_show_in_doc, :authorize,
       :swagger_include_warning_tags, :swagger_content_type_input, :swagger_json_input_uses_refs,
-      :swagger_suppress_warnings, :swagger_api_host, :swagger_generate_x_computed_id_field
+      :swagger_suppress_warnings, :swagger_api_host, :swagger_generate_x_computed_id_field,
+      :swagger_allow_additional_properties_in_response
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
@@ -176,6 +178,7 @@ module Apipie
       @swagger_suppress_warnings = false #[105,100,102]
       @swagger_api_host = "localhost:3000"
       @swagger_generate_x_computed_id_field = false
+      @swagger_allow_additional_properties_in_response = false
     end
   end
 end

data/lib/apipie/dsl_definition.rb

@@ -2,7 +2,7 @@
 
 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
@@ -32,6 +32,7 @@ module Apipie
          :api_args          => [],
          :api_from_routes   => nil,
          :errors            => [],
+         :returns           => {},
          :params            => [],
          :headers           => [],
          :resource_id        => nil,
@@ -309,6 +310,7 @@ module Apipie
       end
     end
 
+
     # this describes the params, it's in separate module because it's
     # used in Validators as well
     module Param
@@ -329,6 +331,13 @@ 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.
@@ -354,6 +363,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

data/lib/apipie/errors.rb

@@ -9,6 +9,12 @@ module Apipie
   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
@@ -51,5 +57,4 @@ module Apipie
       "Invalid parameter '#{@param}' value #{@value.inspect}: #{@error}"
     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]}"
@@ -177,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

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
@@ -34,6 +34,10 @@ module Apipie
         Apipie::ErrorDescription.from_dsl_data(args)
       end
 
+      @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 +50,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]
 
@@ -85,6 +90,25 @@ module Apipie
       all_params.find_all(&:validator)
     end
 
+    def returns_self
+      @returns
+    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 = []
@@ -189,6 +213,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, :allow_blank, :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,
@@ -62,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
@@ -74,11 +83,20 @@ module Apipie
       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?

data/lib/apipie/resource_description.rb

@@ -14,7 +14,7 @@ module Apipie
   class ResourceDescription
 
     attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
-      :_path, :_name, :_params_args, :_errors_args, :_formats, :_parent, :_metadata,
+      :_path, :_name, :_params_args, :_returns_args, :_errors_args, :_formats, :_parent, :_metadata,
       :_headers, :_deprecated
 
     def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
@@ -22,6 +22,7 @@ module Apipie
       @_methods = ActiveSupport::OrderedHash.new
       @_params_args = []
       @_errors_args = []
+      @_returns_args = []
 
       @controller = controller
       @_id = resource_name
@@ -40,6 +41,7 @@ module Apipie
       @_formats = dsl_data[:formats]
       @_errors_args = dsl_data[:errors]
       @_params_args = dsl_data[:params]
+      @_returns_args = dsl_data[:returns]
       @_metadata = dsl_data[:meta]
       @_api_base_url = dsl_data[:api_base_url]
       @_headers = dsl_data[:headers]

data/lib/apipie/response_description.rb

@@ -0,0 +1,125 @@
+module Apipie
+
+  class ResponseDescription
+    class ResponseObject
+      include Apipie::DSL::Base
+      include Apipie::DSL::Param
+
+      attr_accessor :additional_properties
+
+      def initialize(method_description, scope, block)
+        @method_description = method_description
+        @scope = scope
+        @param_group = {scope: scope}
+        @additional_properties = false
+
+        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 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)
+      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