apipie-rails 0.3.6 → 0.9.1

data/lib/apipie/resource_description.rb

@@ -7,20 +7,22 @@ module Apipie
   # 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
+  # id - resource 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)

data/lib/apipie/rspec/response_validation_helper.rb

@@ -0,0 +1,194 @@
+#----------------------------------------------------------------------------------------------
+# response_validation_helper.rb:
+#
+# this is an rspec utility to allow validation of responses against the swagger schema generated
+# from the Apipie 'returns' definition for the call.
+#
+#
+# to use this file in a controller rspec you should
+# require 'apipie/rspec/response_validation_helper' in the spec file
+#
+#
+# this utility provides two mechanisms:  matcher-based validation and auto-validation
+#
+#   matcher-based: an rspec matcher allowing 'expect(response).to match_declared_responses'
+#   auto-validation: all responses returned from 'get', 'post', etc. are automatically tested
+#
+# ===================================
+# Matcher-based validation - example
+# ===================================
+# Assume the file 'my_controller_spec.rb':
+#
+#     require 'apipie/rspec/response_validation_helper'
+#
+#     RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+#
+#     describe "GET stuff with response validation" do
+#       render_views   # this makes sure the 'get' operation will actually
+#                      # return the rendered view even though this is a Controller spec
+#
+#       it "does something" do
+#         response = get :index, {format: :json}
+#
+#         # the following expectation will fail if the returned object
+#         # does not match the 'returns' declaration in the Controller,
+#         # or if there is no 'returns' declaration for the returned
+#         # HTTP status code
+#         expect(response).to match_declared_responses
+#       end
+#     end
+#
+#
+# ===================================
+# Auto-validation
+# ===================================
+# To use auto-validation, at the beginning of the block in which you want to turn on validation:
+#    -) turn on view rendering (by stating 'render_views')
+#    -) turn on response validation by stating 'auto_validate_rendered_views'
+#
+# For example, assume the file 'my_controller_spec.rb':
+#
+#     require 'apipie/rspec/response_validation_helper'
+#
+#     RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+#
+#     describe "GET stuff with response validation" do
+#       render_views
+#       auto_validate_rendered_views
+#
+#       it "does something" do
+#         get :index, {format: :json}
+#       end
+#       it "does something else" do
+#         get :another_index, {format: :json}
+#       end
+#     end
+#
+#     describe "GET stuff without response validation" do
+#       it "does something" do
+#         get :index, {format: :json}
+#       end
+#       it "does something else" do
+#         get :another_index, {format: :json}
+#       end
+#     end
+#
+#
+# Once this is done, responses from http operations ('get', 'post', 'delete', etc.)
+# will fail the test if the response structure does not match the 'returns' declaration
+# on the method (for the actual HTTP status code), or if there is no 'returns' declaration
+# for the HTTP status code.
+#----------------------------------------------------------------------------------------------
+
+
+#----------------------------------------------------------------------------------------------
+# Response validation: core logic  (used by auto-validation and manual-validation mechanisms)
+#----------------------------------------------------------------------------------------------
+class ActionController::Base
+  module Apipie::ControllerValidationHelpers
+    # this method is injected into ActionController::Base in order to
+    # get access to the names of the current controller, current action, as well as to the response
+    def schema_validation_errors_for_response
+      unprocessed_schema = Apipie::json_schema_for_method_response(controller_name, action_name, response.code, true)
+
+      if unprocessed_schema.nil?
+        err = "no schema defined for #{controller_name}##{action_name}[#{response.code}]"
+        return [nil, [err], RuntimeError.new(err)]
+      end
+
+      schema = JSON.parse(JSON(unprocessed_schema))
+
+      error_list = JSON::Validator.fully_validate(schema, response.body, :strict => false, :version => :draft4, :json => true)
+
+      error_object = Apipie::ResponseDoesNotMatchSwaggerSchema.new(controller_name, action_name, response.code, error_list, schema, response.body)
+
+      [schema, error_list, error_object]
+    rescue Apipie::NoDocumentedMethod
+      [nil, [], nil]
+    end
+  end
+
+  include Apipie::ControllerValidationHelpers
+end
+
+module Apipie
+  def self.print_validation_errors(validation_errors, schema, response, error_object=nil)
+    Rails.logger.warn(validation_errors.to_s)
+    if Rails.env.test?
+      puts "schema validation errors:"
+      validation_errors.each { |e| puts "--> #{e.to_s}" }
+      puts "schema:  #{schema.nil? ? '<none>' : JSON(schema)}"
+      puts "response: #{response.body}"
+      raise error_object if error_object
+    end
+  end
+end
+
+#---------------------------------
+# Manual-validation (RSpec matcher)
+#---------------------------------
+RSpec::Matchers.define :match_declared_responses do
+  match do |actual|
+    (schema, validation_errors) = subject.send(:schema_validation_errors_for_response)
+    valid = (validation_errors == [])
+    Apipie::print_validation_errors(validation_errors, schema, response) unless valid
+
+    valid
+  end
+end
+
+
+#---------------------------------
+# Auto-validation logic
+#---------------------------------
+module RSpec::Rails::ViewRendering
+  # Augment the RSpec DSL
+  module ClassMethods
+    def auto_validate_rendered_views
+      before do
+        @is_response_validation_on = true
+      end
+
+      after do
+        @is_response_validation_on = false
+      end
+    end
+  end
+end
+
+
+ActionController::TestCase::Behavior.instance_eval do
+  # instrument the 'process' method in ActionController::TestCase to enable response validation
+  module Apipie::ResponseValidationHelpers
+    @is_response_validation_on = false
+    def process(*, **)
+      result = super
+      validate_response if @is_response_validation_on
+
+      result
+    end
+
+    def validate_response
+      controller.send(:validate_response_and_abort_with_info_if_errors)
+    end
+  end
+
+  prepend Apipie::ResponseValidationHelpers
+end
+
+
+class ActionController::Base
+  module Apipie::ControllerValidationHelpers
+    def validate_response_and_abort_with_info_if_errors
+
+      (schema, validation_errors, error_object) = schema_validation_errors_for_response
+
+      valid = (validation_errors == [])
+      if !valid
+        Apipie::print_validation_errors(validation_errors, schema, response, error_object)
+      end
+    end
+  end
+end
+
+

data/lib/apipie/static_dispatcher.rb

@@ -8,9 +8,12 @@ module Apipie
     end
 
     def match?(path)
-      path = path.dup
+      # Replace all null bytes
+      path = ::Rack::Utils.unescape(path || '')
+                          .encode(Encoding::UTF_8, invalid: :replace, replace: '')
+                          .gsub(/\x0/, '')
 
-      full_path = path.empty? ? @root : File.join(@root, ::Rack::Utils.unescape(path))
+      full_path = path.empty? ? @root : File.join(@root, path)
       paths = "#{full_path}#{ext}"
 
       matches = Dir[paths]