apipie-rails 0.3.6 → 0.9.1

data/lib/apipie/extractor.rb

@@ -9,16 +9,16 @@ require 'apipie/extractor/collector'
 class Apipie::Railtie
   initializer 'apipie.extractor' do |app|
     ActiveSupport.on_load :action_controller do
-      before_filter do |controller|
+      before_action do |controller|
         if Apipie.configuration.record
           Apipie::Extractor.call_recorder.analyse_controller(controller)
         end
       end
     end
     app.middleware.use ::Apipie::Extractor::Recorder::Middleware
-    ActionController::TestCase::Behavior.instance_eval do
-      include Apipie::Extractor::Recorder::FunctionalTestRecording
-    end
+
+    ActionController::TestCase.send(:prepend, Apipie::Extractor::Recorder::FunctionalTestRecording)
+    ActionController::TestCase::Behavior.send(:prepend, Apipie::Extractor::Recorder::FunctionalTestRecording)
   end
 end
 
@@ -154,7 +154,7 @@ module Apipie
       def update_api_descriptions
         apis_from_docs = all_apis_from_docs
         @apis_from_routes.each do |(controller, action), new_apis|
-          method_key = "#{Apipie.get_resource_name(controller.constantize)}##{action}"
+          method_key = "#{Apipie.get_resource_name(controller.safe_constantize || next)}##{action}"
           old_apis = apis_from_docs[method_key] || []
           new_apis.each do |new_api|
             new_api[:path].sub!(/\(\.:format\)$/,"") if new_api[:path]

data/lib/apipie/generator/generator.rb

@@ -0,0 +1,2 @@
+module Apipie::Generator
+end

data/lib/apipie/generator/swagger/swagger.rb

@@ -0,0 +1,2 @@
+module Apipie::Generator::Swagger
+end

data/lib/apipie/generator/swagger/type.rb

@@ -0,0 +1,16 @@
+class Apipie::Generator::Swagger::Type
+  attr_reader :str_format
+
+  def initialize(type, str_format = nil)
+    @type = type
+    @str_format = str_format
+  end
+
+  def to_s
+    @type
+  end
+
+  def ==(other)
+    other.to_s == self.to_s
+  end
+end

data/lib/apipie/generator/swagger/type_extractor.rb

@@ -0,0 +1,70 @@
+class Apipie::Generator::Swagger::TypeExtractor
+  TYPES = {
+    numeric: 'number',
+    hash: 'object',
+    array: 'array',
+    enum: 'enum',
+
+    # see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
+    integer: Apipie::Generator::Swagger::Type.new('integer', 'int32'),
+    long: Apipie::Generator::Swagger::Type.new('integer', 'int64'),
+    number: Apipie::Generator::Swagger::Type.new('number'),
+    float: Apipie::Generator::Swagger::Type.new('number', 'float'),
+    double: Apipie::Generator::Swagger::Type.new('number', 'double'),
+    string: Apipie::Generator::Swagger::Type.new('string'),
+    byte: Apipie::Generator::Swagger::Type.new('string', 'byte'),
+    binary: Apipie::Generator::Swagger::Type.new('string', 'binary'),
+    boolean: Apipie::Generator::Swagger::Type.new('boolean'),
+    date: Apipie::Generator::Swagger::Type.new('string', 'date'),
+    dateTime: Apipie::Generator::Swagger::Type.new('string', 'date-time'),
+    password: Apipie::Generator::Swagger::Type.new('string', 'password')
+  }
+
+  # @param [Apipie::Validator::BaseValidator, ResponseDescriptionAdapter::PropDesc::Validator, nil] validator
+  def initialize(validator)
+    @validator = validator
+  end
+
+  # @param [Hash<Symbol, Apipie::Generator::Swagger::Warning>] warnings
+  def extract_with_warnings(warnings = {})
+    if boolean? && warnings[:boolean].present?
+      Apipie::Generator::Swagger::WarningWriter.instance.warn(warnings[:boolean])
+    end
+
+    extract
+  end
+
+  private
+
+  def extract
+    expected_type =
+      if string?
+        :string
+      elsif boolean?
+        :boolean
+      elsif enum?
+        :enum
+      else
+        @validator.expected_type.to_sym
+      end
+
+    TYPES[expected_type] || @validator.expected_type
+  end
+
+  def string?
+    @validator.blank?
+  end
+
+  def enum?
+    @validator.is_a?(Apipie::Validator::EnumValidator) ||
+      (@validator.respond_to?(:is_enum?) && @validator.is_enum?)
+  end
+
+  def boolean?
+    @_boolean ||= enum? && boolean_values?
+  end
+
+  def boolean_values?
+    @validator.values.to_set == Set.new([true, false])
+  end
+end

data/lib/apipie/generator/swagger/warning.rb

@@ -0,0 +1,77 @@
+class Apipie::Generator::Swagger::Warning
+  MISSING_METHOD_SUMMARY_CODE = 100
+  ADDED_MISSING_SLASH_CODE = 101
+  NO_RETURN_CODES_SPECIFIED_CODE = 102
+  HASH_WITHOUT_INTERNAL_TYPESPEC_CODE = 103
+  OPTIONAL_PARAM_IN_PATH_CODE = 104
+  OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE = 105
+  PARAM_IGNORED_IN_FORM_DATA_CODE = 106
+  PATH_PARAM_NOT_DESCRIBED_CODE = 107
+  INFERRING_BOOLEAN_CODE = 108
+
+  CODES = {
+    missing_method_summary: MISSING_METHOD_SUMMARY_CODE,
+    added_missing_slash: ADDED_MISSING_SLASH_CODE,
+    no_return_codes_specified: NO_RETURN_CODES_SPECIFIED_CODE,
+    hash_without_internal_typespec: HASH_WITHOUT_INTERNAL_TYPESPEC_CODE,
+    optional_param_in_path: OPTIONAL_PARAM_IN_PATH_CODE,
+    optional_without_default_value: OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
+    param_ignored_in_form_data: PARAM_IGNORED_IN_FORM_DATA_CODE,
+    path_param_not_described_code: PATH_PARAM_NOT_DESCRIBED_CODE,
+    inferring_boolean: INFERRING_BOOLEAN_CODE
+  }
+
+  MESSAGES = {
+    MISSING_METHOD_SUMMARY_CODE => "Missing short description for method",
+    ADDED_MISSING_SLASH_CODE => "Added missing / at beginning of path: %{path}",
+    HASH_WITHOUT_INTERNAL_TYPESPEC_CODE => "The parameter :%{parameter} is a generic Hash without an internal type specification",
+    NO_RETURN_CODES_SPECIFIED_CODE => "No return codes ('errors') specified",
+    OPTIONAL_PARAM_IN_PATH_CODE => "The parameter :%{parameter} is 'in-path'.  Ignoring 'not required' in DSL",
+    OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE => "The parameter :%{parameter} is optional but default value is not specified (use :default_value => ...)",
+    PARAM_IGNORED_IN_FORM_DATA_CODE => "Ignoring param :%{parameter} -- cannot include Hash without fields in a formData specification",
+    PATH_PARAM_NOT_DESCRIBED_CODE => "The parameter :%{name} appears in the path %{path} but is not described",
+    INFERRING_BOOLEAN_CODE => "The parameter [%{parameter}] is Enum with [true, false] values. Inferring 'boolean'"
+  }
+
+  attr_reader :code
+
+  def initialize(code, info_message, method_id)
+    @code = code
+    @info_message = info_message
+    @method_id = method_id
+  end
+
+  def id
+    "#{@method_id}#{@code}#{@info_message}"
+  end
+
+  def warning_message
+    "WARNING (#{@code}): [#{@method_id}] -- #{@info_message}"
+  end
+
+  def warn
+    Warning.warn(warning_message)
+  end
+
+  def warn_through_writer
+    Apipie::Generator::Swagger::WarningWriter.instance.warn(self)
+  end
+
+  # @param [Integer] code
+  # @param [Hash] message_attributes
+  #
+  # @return [Apipie::Generator::Swagger::Warning]
+  def self.for_code(code, method_id, message_attributes = {})
+    if !CODES.values.include?(code)
+      raise ArgumentError, 'Unknown warning code'
+    end
+
+    info_message = if message_attributes.present?
+                     self::MESSAGES[code] % message_attributes
+                   else
+                     self::MESSAGES[code]
+                   end
+
+    Apipie::Generator::Swagger::Warning.new(code, info_message, method_id)
+  end
+end

data/lib/apipie/generator/swagger/warning_writer.rb

@@ -0,0 +1,48 @@
+class Apipie::Generator::Swagger::WarningWriter
+  include Singleton
+
+  def initialize
+    @issued_warnings = []
+  end
+
+  # @param [Apipie::Generator::Swagger::Warning] warning
+  def warn(warning)
+    return if muted_warning?(warning)
+
+    warning.warn
+
+    @issued_warnings << warning.id
+  end
+
+  def issued_warnings?
+    @issued_warnings.count > 0
+  end
+
+  private
+
+  # @param [Apipie::Generator::Swagger::Warning] warning
+  #
+  # @return [TrueClass, FalseClass]
+  def muted_warning?(warning)
+    @issued_warnings.include?(warning.id) ||
+      suppressed_warning?(warning.code) ||
+      suppress_warnings?
+  end
+
+  # @param [Integer] warning_number
+  #
+  # @return [TrueClass, FalseClass]
+  def suppressed_warning?(warning_number)
+    suppress_warnings_config.is_a?(Array) && suppress_warnings_config.include?(warning_number)
+  end
+
+  # @return [TrueClass, FalseClass]
+  def suppress_warnings?
+    suppress_warnings_config == true
+  end
+
+  # @return [FalseClass, TrueClass, Array]
+  def suppress_warnings_config
+    Apipie.configuration.swagger_suppress_warnings
+  end
+end

data/lib/apipie/markup.rb

@@ -4,20 +4,23 @@ module Apipie
 
     class RDoc
 
-      def initialize
-        require 'rdoc'
-        require 'rdoc/markup/to_html'
-        if Gem::Version.new(::RDoc::VERSION) < Gem::Version.new('4.0.0')
-          @rdoc ||= ::RDoc::Markup::ToHtml.new()
-        else
-          @rdoc ||= ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
-        end
-      end
-
       def to_html(text)
-        @rdoc.convert(text)
+        rdoc.convert(text)
       end
 
+      private
+
+      def rdoc
+        @rdoc ||= begin
+          require 'rdoc'
+          require 'rdoc/markup/to_html'
+          if Gem::Version.new(::RDoc::VERSION) < Gem::Version.new('4.0.0')
+            ::RDoc::Markup::ToHtml.new()
+          else
+            ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
+          end
+        end
+      end
     end
 
     class Markdown

data/lib/apipie/method_description/api.rb

@@ -0,0 +1,12 @@
+class Apipie::MethodDescription::Api
+  attr_accessor :short_description, :path, :http_method, :from_routes,
+    :options, :returns
+
+  def initialize(method, path, desc, options)
+    @http_method = method.to_s
+    @path = path
+    @short_description = desc
+    @from_routes = options[:from_routes]
+    @options = options
+  end
+end

data/lib/apipie/method_description/apis_service.rb

@@ -0,0 +1,82 @@
+# Service that builds the appropriate Apipie::MethodDescription::Api
+# required by Apipie::MethodDescription
+#
+class Apipie::MethodDescription::ApisService
+  # @param [Apipie::ResourceDescription] resource
+  # @param [Symbol] controller_action
+  # @param [Hash] dsl
+  def initialize(resource, controller_action, dsl)
+    @resource = resource
+    @controller_action = controller_action
+    @dsl = dsl
+  end
+
+  # @return [Array<Apipie::MethodDescription::Api>]
+  def call
+    api_args.map do |http_method, path, desc, opts|
+      Apipie::MethodDescription::Api.new(
+        http_method,
+        concern_subst(path),
+        concern_subst(desc),
+        opts
+      )
+    end
+  end
+
+  private
+
+  def concern_subst(path)
+    return if path.blank?
+
+    if from_concern?
+      @resource.controller._apipie_perform_concern_subst(path)
+    else
+      path
+    end
+  end
+
+  # @return [Array<Array>]
+  def api_args
+    return @dsl[:api_args] if !api_from_routes?
+
+    api_args = @dsl[:api_args].dup
+
+    api_args_from_routes = routes.map do |route_info|
+      [
+        route_info[:verb],
+        route_info[:path],
+        route_info[:desc],
+        (route_info[:options] || {}).merge(from_routes: true)
+      ]
+    end
+
+    api_args.concat(api_args_from_routes)
+  end
+
+  def api_from_routes?
+    @dsl[:api_from_routes].present?
+  end
+
+  def from_concern?
+    @dsl[:from_concern] == true
+  end
+
+  def description
+    @dsl[:api_from_routes][:desc]
+  end
+
+  def options
+    @dsl[:api_from_routes][:options]
+  end
+
+  # @return [Array<Hash>]
+  def routes
+    Apipie.routes_for_action(
+      @resource.controller,
+      @controller_action,
+      { desc: description, options: options }
+    )
+  end
+end
+
+

data/lib/apipie/method_description.rb

@@ -1,31 +1,14 @@
-require 'set'
 module Apipie
 
   class MethodDescription
-
-    class Api
-
-      attr_accessor :short_description, :path, :http_method, :from_routes, :options
-
-      def initialize(method, path, desc, options)
-        @http_method = method.to_s
-        @path = path
-        @short_description = desc
-        @from_routes = options[:from_routes]
-        @options = options
-      end
-
-    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
       @resource = resource
       @from_concern = dsl_data[:from_concern]
-      @apis = api_data(dsl_data).map do |mthd, path, desc, opts|
-        MethodDescription::Api.new(mthd, concern_subst(path), concern_subst(desc), opts)
-      end
+      @apis = ApisService.new(resource, method, dsl_data).call
 
       desc = dsl_data[:description] || ''
       @full_description = Apipie.markup_to_html(desc)
@@ -34,6 +17,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 +35,8 @@ module Apipie
 
       @params_ordered = dsl_data[:params].map do |args|
         Apipie::ParamDescription.from_dsl_data(self, args)
-      end
+      end.reject(&:response_only?)
+
       @params_ordered = ParamDescription.unify(@params_ordered)
       @headers = dsl_data[:headers]
 
@@ -65,6 +55,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 +75,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(&:_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 +147,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 +169,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),
@@ -162,29 +185,18 @@ module Apipie
 
     private
 
-    def api_data(dsl_data)
-      ret = dsl_data[:api_args].dup
-      if dsl_data[:api_from_routes]
-        desc = dsl_data[:api_from_routes][:desc]
-        options = dsl_data[:api_from_routes][:options]
-
-        api_from_routes = Apipie.routes_for_action(resource.controller, method, {:desc => desc, :options => options}).map do |route_info|
-          [route_info[:verb],
-           route_info[:path],
-           route_info[:desc],
-           (route_info[:options] || {}).merge(:from_routes => true)]
-        end
-        ret.concat(api_from_routes)
-      end
-      ret
-    end
-
     def merge_params(params, new_params)
       new_param_names = Set.new(new_params.map(&:name))
       params.delete_if { |p| new_param_names.include?(p.name) }
       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 }.
@@ -212,16 +224,6 @@ module Apipie
       example << "\n" << format_example_data(ex[:response_data]).to_s if ex[:response_data]
       example
     end
-
-    def concern_subst(string)
-      return if string.nil?
-      if from_concern?
-        resource.controller._apipie_perform_concern_subst(string)
-      else
-        string
-      end
-    end
-
   end
 
 end

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,31 +78,58 @@ 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?
-      if (!@allow_nil && value.nil?) || !@validator.valid?(value)
-        error = @validator.error
+      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
@@ -111,6 +160,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 +181,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 +201,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?